org.vishia.event

Class TimeOrder

java.lang.Object

org.vishia.event.EventSource

org.vishia.event.TimeOrder

public class TimeOrder
extends EventSource

This class builds a time order instance usable as timeout for state machines or other time orders. It is intent do use for EventTimerThread or another implementation using EventTimerThread_ifc. It is also used for the vishia graphical programming (GRAL) referenced in org.vishia.gral.base.GralGraphicOrder and also for FileRemoteProgressEvData. It is referenced by EventWithDst#timeOrder and only constructed in that class calling EventWithDst#EventWithDst(String, EventTimerThread_ifc, EventSource, EventConsumer, EventThread_ifc) or enhanced classes from EventWithDst if the event should be delayed.
An EventCmdtype with TimeOrderCmd is used inside StateMachine as persistent instance of any parallel state machine or of the top state if timeouts are used in the states.

Activate the timeout event:

   myEvent.timeOrder.activate(7000);  //activate execution of the event in 7 seconds.
 

• Constructor for a given event of any derived specific type: TimeOrder#TimeEntry(String, EventTimerThread_ifc, EventWithDst).
• methods to activate: activate(int), activateAt(long), activateAt(long, long)
• Remove a currently timeout: deactivate()
• Check: timeExecution(), timeExecutionLatest(), timeToExecution() used()
• see EventTimerThread
• see StateMachine

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	bAwaiting Set if #awaitExecution(int, int) is called.
private boolean	bCyclic If this bit is set, repeatCyclic() activates again.
protected boolean	bEventException True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumerException.
protected boolean	bEventExecuted True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumed.
protected boolean	bHoldTimeorder If true then the current active time order should not be send as event if the time is expired, because some data are changed.
protected boolean	bNotifyAlsoOnException
protected boolean	bTimeElapsed
protected boolean	bTimeOrderFinished True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumFinished.
protected int	ctConsumed
int	dbgctWindup It is counted only.
protected EventWithDst	event
java.lang.String	name
private static long	serialVersionUID
private int	timeCycle The cycle of execution for the first time and cyclic.
private int	timeCycleFirst The cycle of execution for the first time and cyclic.
protected long	timeExecution If not 0, it is the time to execute it.
protected long	timeExecutionLatest If not 0, it is the last time to execute it if the execution will be deferred by additional invocation of activateAt(long) while it is activated already.
EventTimerThread_ifc	timerThread
static java.lang.String	version Version and history: 2023-03-12 new: bHoldTimeorder, hold() to change data, prevent processing in EventTimerThread 2023-02-21 new: activateCyclic().

Fields inherited from class org.vishia.event.EventSource

nullSource

Constructor Summary

Constructors

Constructor and Description
TimeOrder(java.lang.String name, EventTimerThread_ifc timerThread, EventSource src, EventConsumer consumer, EventThread_ifc evThread) Constructs a time order for usage.
TimeOrder(java.lang.String name, EventTimerThread_ifc timerThread, EventWithDst event) Construction of a time order with any desired specific event to execute.

Method Summary

Modifier and Type	Method and Description
void	activate(int millisec) Activate the time order to send the event for the given laps of time.
void	activateAt(long date) Enters the TimeEntry to activates the event to the given timestamp.
void	activateAt(long executionTime, long latest) Enters the TimeEntry to activates the event to the given timestamp with a given latest time stamp.
void	activateCyclic() Activate the time order for the first time from the source of the event.
void	clear() Clears the order, set to 0 all data excluded timeCycleFirst and timeCycle and removes the order from the queue and also a pending event from the queue.
void	deactivate() Remove this from the queue of timer events and orders
EventWithDst	event()
boolean	hold() Prevent activating a time order because some data may be changed just now.
boolean	isExecuted() Quest whether the time order was finished executing.
void	notifyConsumed(int state) This operation should not called by the user.
(package private) void	repeatCyclic() Repeat activating the time order with the cycle.
void	setCycle(int first, int cycle) Sets the cycle of the event for activateCyclic().
(package private) void	setEvent(EventWithDst event)
long	timeExecution() Returns the time stamp where the time is elapsed
long	timeExecutionLatest() Returns the time stamp where the time is elapsed latest.
int	timeToExecution() Checks whether it should be executed.
boolean	used()
boolean	XXXawaitExecution(int timeout, boolean bAlsoOnException) Waits for execution in any other thread.

Methods inherited from class org.vishia.event.EventSource

notifyDequeued, notifyRelinquished, notifyShouldOccupyButInUse, notifyShouldSentButInUse, notifyUnexpectedException, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

version

public static final java.lang.String version

Version and history:

• 2023-03-12 new: bHoldTimeorder, hold() to change data, prevent processing in EventTimerThread
• 2023-02-21 new: activateCyclic(). The approach is, that the activating must not initiate from the receiver because in a remote situation (network device) the receiver has no access to the TimeOrder. Instead the sender should do it. Hence the setCycle(int, int) should be called on time to determine the cycle. The activateCyclic() should be called only one time if the sender gets active. The repeatCyclic() is set by the EventTimerThread if one event is fired. clear() or deactivate() removes this repeatCyclic() behavior.
• 2023-02-09 refactoring, deferred time orders etc. The TimeOrder is now final aggregated from an EventWithDst if necessary. It aggregates the event by itself. Execution is done only via the event() and its EventWithDst.evDst.
• 2022-09-24 Some comments and changed in activateAt(long, long) while searching the problem that the execution sometimes hangs. Now it does not hang since ~10 min , but the reason is not fully clarified. Before, the problem was that the thread has used its 10 seconds waiting time if the event queue is empty. It seems to be a missing notify(), but the notify() was programmed. The problem occurs in the Gral vishiaGui with CurveView for redraw events.
• 2015-01-02 Hartmut created: as super class of TimeOrder and as event for timeout for state machines.

Copyright/Copyleft: For this source the LGPL Lesser General Public License, published by the Free Software Foundation is valid. It means:

1. You can use this source without any restriction for any desired purpose.
2. You can redistribute copies of this source to everybody.
3. Every user of this source, also the user of redistribute copies with or without payment, must accept this license for further using.
4. But the LPGL is not appropriate for a whole software product, if this source is only a part of them. It means, the user must publish this part of source, but don't need to publish the whole source of the own product.
5. You can study and modify (improve) this source for own using or for redistribution, but you have to license the modified sources likewise under this LGPL Lesser General Public License. You mustn't delete this Copyright/Copyleft inscription in this source file.

If you are indent to use this sources without publishing its usage, you can get a second license subscribing a special contract with the author.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

See Also:

Constant Field Values

name

public final java.lang.String name

event

protected EventWithDst event

timerThread

public final EventTimerThread_ifc timerThread

timeCycleFirst

private int timeCycleFirst

The cycle of execution for the first time and cyclic.

timeCycle

private int timeCycle

The cycle of execution for the first time and cyclic.

bCyclic

private boolean bCyclic

If this bit is set, repeatCyclic() activates again.

timeExecution

protected long timeExecution

If not 0, it is the time to execute it. Elsewhere it should be delayed.

timeExecutionLatest

protected long timeExecutionLatest

If not 0, it is the last time to execute it if the execution will be deferred by additional invocation of activateAt(long) while it is activated already.

bAwaiting

protected boolean bAwaiting

Set if #awaitExecution(int, int) is called. It means a thread is waiting. this.notify() is necessary.

bHoldTimeorder

protected boolean bHoldTimeorder

If true then the current active time order should not be send as event if the time is expired, because some data are changed.

bNotifyAlsoOnException

protected boolean bNotifyAlsoOnException

bTimeElapsed

protected boolean bTimeElapsed

bEventException

protected boolean bEventException

True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumerException.

ctConsumed

protected int ctConsumed

bEventExecuted

protected boolean bEventExecuted

True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumed.

bTimeOrderFinished

protected boolean bTimeOrderFinished

True if EventConsumer.processEvent(java.util.EventObject) has returned the bit EventConsumer.mEventConsumFinished.

dbgctWindup

public int dbgctWindup

It is counted only. Used for debug. Possible to set.

Constructor Detail

TimeOrder

public TimeOrder(java.lang.String name,
                 EventTimerThread_ifc timerThread,
                 EventSource src,
                 EventConsumer consumer,
                 EventThread_ifc evThread)

Constructs a time order for usage. The time order instance may be static usual (permanent referenced) and not allocated on demand (with new) because it is used whenever a special state is entered.

Parameters:

name - for debugging and log

timerThread - where the time entry should be used in, it is determined.

src - the event is occupied with this given EventSource instance.

consumer - The destination object for the event. If it is null nothing will be executed if the event is expired. But you can set the consumer with #occupy(EventSource, EventConsumer, EventThread_ifc, boolean) or with #setDst(EventConsumer) afterwards

evThread - if null, then the event is handled by the same thread as the timerThread, immediately after expire. It means the timeout is handled before the other queued events are handled. This is important for state machine. It means if a timeout transition has its timeout, then this is prior.
If you give the same thread as timerThread (not null), then the event is firstly enqueued in the own event queue after expiring. It means events which are queued before already are first executed. For state machines this means, if just a timeout has expired but there are other events given in the queue, the other events changes the state before and the timeout event may be not used. The difference is only in the small time of expiring.
If this is another thread than timerThread, then the event is handled in the other thread. Instead execution with EventConsumer.processEvent(java.util.EventObject) it is queued in the other thread and there executed. With this approach a central timer can be used for several statemachine threads.

TimeOrder

public TimeOrder(java.lang.String name,
                 EventTimerThread_ifc timerThread,
                 EventWithDst event)

Construction of a time order with any desired specific event to execute. The ctor is package private, only used in EventWithDst#EventWithDst(String, EventTimerThread_ifc, EventSource, EventConsumer, EventThread_ifc). It means the user constructs the event with time order (any derived event type), and the ctor of the event calls this ctor to organize a bidirectional aggregation.

Parameters:

name - for debugging and log

timerThread - where the time entry should be used in, if null use the event's thread.

event - The event for execution.

Throws:

java.lang.IllegalArgumentException - if timerThread argument is null and the event do not refer an EventTimerThread_ifc

Method Detail

setEvent

void setEvent(EventWithDst event)

setCycle

public void setCycle(int first,
                     int cycle)

Sets the cycle of the event for activateCyclic(). If this operation is never called, the initial values are valid.

Parameters:

first - Milliseconds from activateCyclic() to the first invocation, default 1 ms.

cycle - Milliseconds for repeated call, used from repeatCyclic().

event

public EventWithDst event()

clear

public void clear()

Clears the order, set to 0 all data excluded timeCycleFirst and timeCycle and removes the order from the queue and also a pending event from the queue. If any thread has called #awaitExecution(int, boolean) this thread is notified firstly to prevent a hanging thread.

activateCyclic

public final void activateCyclic()

Activate the time order for the first time from the source of the event. This should be called by the source of the event which gives also feedbacks. It calls activate(int) with the first time set on setCycle(int, int), default 1 ms.

repeatCyclic

final void repeatCyclic()

Repeat activating the time order with the cycle. This is called in the EventTimerThread if cyclic is activated, after one is expired. Hence it is package private. It calls activate(int) with the timeCycle.

hold

public final boolean hold()

Prevent activating a time order because some data may be changed just now. After changing data a new activate(int) should be called to activate again.

Returns:

true if the time is expired or the timeOrder is free. It means the time Order should be entered newly. But it is usual no difference, activate(int) should be called anyway.

activate

public final void activate(int millisec)

Activate the time order to send the event for the given laps of time. If the event is activated already for a shorter time, the activation time is deferred to this given time but not later than a latest time given with activateAt(long, long).

Parameters:

millisec - if a negative value or a value less then 3 is given the event is processed immediately.

See Also:

activateAt(long, long).

activateAt

public final void activateAt(long date)

Enters the TimeEntry to activates the event to the given timestamp.
If the event is entered already for a shorter time, and this is also the latest time, then nothing is done. The event will be activated at the time as given before. See also activateAt(long, long).

Parameters:

date - The absolute time stamp in seconds after 1970 UTC like given with System.currentTimeMillis(). To set a relative time you must write

     myEvent.activateAt(System.currentTimeMillis() + delay);
   

activateAt

public final void activateAt(long executionTime,
                             long latest)

Enters the TimeEntry to activates the event to the given timestamp with a given latest time stamp. This is proper for deferment an event by given a new time also by call of activateAt(long) or activate(int). If the event is activated already for a shorter time, then the activation time is deferred to this given time but not later than a latest time given with activateAt(long, long).

If the TimeOrder is not in the time queue but is in execution just now, the execution is not influenced. Instead, as desired, the TimeOrder is activated for a further execution in the given time. Normally this new execution time should be later than the finishing of the current execution. If this is not so, the new execution is done after the current one. TODO

Parameters:

executionTime - The time stamp for desired execution, can be delayed on second calls.

latest - The latest time stamp where the event should be processed though it is delayed. If the event is activated already for a earlier latest time, this argument is ignored. The earlier latest time is valid. Use deactivate() before this method to set the latest processing time newly.

See Also:

activateAt(long).

deactivate

public final void deactivate()

Remove this from the queue of timer events and orders

timeExecution

public final long timeExecution()

Returns the time stamp where the time is elapsed

Returns:

milliseconds after 1970, 0 if the event is not activated yet.

timeExecutionLatest

public final long timeExecutionLatest()

Returns the time stamp where the time is elapsed latest.

Returns:

milliseconds after 1970, 0 if the event is not activated yet.

used

public final boolean used()

isExecuted

public final boolean isExecuted()

Quest whether the time order was finished executing.

Returns:

true if it was executed. Returns bEventExecuted.

notifyConsumed

public void notifyConsumed(int state)

This operation should not called by the user. It is intent to call via the interface EventSource from the event management classes, especially EventTimerThread or adequate implementations of EventThread_ifc if EventConsumer.processEvent(java.util.EventObject) is returned.

Overrides:

notifyConsumed in class EventSource

Parameters:

state - the return value of processEvent, bits 31..24 is the EventWithDst.ctConsumed.

timeToExecution

public final int timeToExecution()

Checks whether it should be executed.

Returns:

time in milliseconds for first execution or value <0 if it is expired (to execute immediately) or the Integer.MAX_VALUE if it is not in use (expires in a very long time).

XXXawaitExecution

public boolean XXXawaitExecution(int timeout,
                                 boolean bAlsoOnException)

Waits for execution in any other thread. This method can be called in any thread, especially in that thread, which initializes the request.

Parameters:

ctDoneRequested - Number of executions requested.

timeout - maximal waiting time in milliseconds, 0 means wait forever.

Returns:

true if it is executed the requested number of.