EventTimerThread

java.lang.Object
- org.vishia.event.EventTimerThread

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, EventThread_ifc, EventTimerThread_ifc, InfoAppend

Direct Known Subclasses:

OrderListExecuter
```
public class EventTimerThread
extends java.lang.Object
implements EventTimerThread_ifc, java.io.Closeable, InfoAppend
```
This class stores events, starts the processing of the events in one thread and manages and executes time orders in the same thread. An instance of this class is the main instance to execute state machines in one thread. The methods of this class except start() and close() are used from instances of EventWithDst, TimeOrder and TimeOrder internally. They should not be invoked by an application directly. But if any other event derived from EventObject is used then the methods setStdEventProcessor(EventConsumer), storeEvent(EventObject) and maybe removeFromQueue(EventObject) should be used.

To instantiate and start use
```
 
  EventTimerThread myExecutionThread = new EventTimerThread("thread-name");
  myExecutionThread.start();
 
```
On end of the application close() should be invoked to end the thread.

To add any event of derived type of EventWithDst from any other thread use this instance as argument for the event:
```
 
  MyEventWithDst event = new MyEventWithDst(source, dst, myExecutionThread);
  //or:
  event.occupy(source, dst, myExecutionThread, ...)
  event.sendEvent();
 
```
To add any other type of EventObject you should set a setStdEventProcessor(EventConsumer). Then use
```
 
  myExecutionThread.storeEvent(eventObject);
 
```
This class is used as time manager too. It manages and executes TimeOrder which are used especially for StateMachine, but it can execute TimeOrder in this thread too. To add a timeout event or a time order use the methods of the TimeOrder.activateAt(long) etc:
```
 
  TimeOrder myTimeOrder = new TimeOrder("name", myExecutionThread) {
    QOverride protected void executeOrder(){ ...execution of the time order ...}
  };
  ...
  myTimeOrder.activate(100);  //in 100 milliseconds.
 
```
That routine invokes the routine addTimeEntry(TimeOrder) of this class.

This class starts a thread. The thread sleeps if no event or time order is given.

Events are stored in a ConcurrentLinkedQueue which is thread-safe to enqueue events from any thread with the method storeEvent(EventObject). Then Object.notify() is called to weak up the thread if it sleeps. Then the all stored events are dequeued and its execution routine of EventConsumer.processEvent(EventObject) is invoked. The events are processed one after another. The execution routine is usual a StateMachine but any other EventConsumer is able to use too.

TimeOrder are stored in another ConcurrentLinkedQueue. The absolute time of the next execution is stored in the internal value of timeCheckNew. The thread sleeps either till this time is expired or till an event is given. If the time is expired all stored time orders are checked whether its time is elapsed. Then either the EventConsumer.processEvent(EventObject) is invoked if an TimeOrder is given or a TimeOrder has a destination. Elsewhere the TimeOrder#doExecute is invoked to execute the TimeOrder#executeOrder() in this thread.

An event can be removed from the queue if it is not executed up to now. The routine removeFromQueue(EventObject) is invoked if an event should be EventWithDst.occupyRecall(EventSource, boolean). That is if the event should be used newly.

Note: An TimeOrder can be removed from execution with the method TimeOrder.deactivate(). Adequate is done with removeTimeEntry(TimeOrder).

Field Summary

Fields
Modifier and Type	Field and Description
`protected boolean`	`bThreadRun`
`private int`	`ctWaitEmptyQueue`
`private int`	`debugPrint` Bit variable to control some System.out.printf debug outputs.
`(package private) int`	`debugPrintViewDelayed` Only for inspector or debug access: Use it to show delaying.
`private int`	`delayMax` The delay [ms] for one step if nothing is to do.
`private EventConsumer`	`eventProcessor`
`private java.util.concurrent.atomic.AtomicBoolean`	`extEventSet` Set if any external event is set.
`protected int`	`maxCtWaitEmptyQueue`
`private boolean`	`preserveRecursiveInfoAppend`
`private java.util.concurrent.ConcurrentLinkedQueue<TimeOrder>`	`queueDelayedOrders` Queue of orders which are executed with delay yet.
`private java.util.concurrent.ConcurrentLinkedQueue<java.util.EventObject>`	`queueEvents` Queue of orders which are executed with delay yet.
`private java.util.concurrent.ConcurrentLinkedQueue<TimeOrder>`	`queueOrdersToExecute` Temporary used instance for orders ready to execute while `runTimer` organizes the delayed orders.
`private java.lang.Runnable`	`runTimer` Instance as Runnable contains invocation of `stepThread()` and the `Object.wait()` with the calculated timeWait.
`protected boolean`	`startOnDemand`
`protected char`	`stateThreadTimer` State of the thread, used for debug and mutex mechanism.
`protected java.lang.String`	`threadName`
`protected java.lang.Thread`	`threadTimer` The thread which executes delayed wake up.
`protected long`	`timeCheckNew` timestamp for a new time entry.
`private long`	`timeSleep` The time on start waiting
`static java.lang.String`	`version` Version, license and history.

Constructor Summary

Constructors
Constructor and Description

EventTimerThread(java.lang.String threadName)
Creates the Manager for time orders.

Constructors
Constructor and Description
`EventTimerThread(java.lang.String threadName)` Creates the Manager for time orders.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`char`	`addTimeEntry(TimeOrder order)` Adds a timeout event or a time order with given execution time.
`private boolean`	`checkEventAndRun()` Applies an events from the queue to the destination in the event thread.
`private int`	`checkTimeOrders()` Check all time orders whether there are expired, or if not calculate the next time to check.
`void`	`close()` Should only be called on end of the whole application to finish the timer thread.
`protected void`	`createThread_()` This operation can be overridden if another thread organization, especially another `stepThread()` should be used.
`char`	`getState()` Returns the current state of the thread.
`java.lang.CharSequence`	`infoAppend(java.lang.StringBuilder u)` Info for debugging This operation can be overridden for another thread organization.
`boolean`	`isBusy()` Checks whether the thread is busy.
`boolean`	`isCurrentThread()` Returns true if the current thread is the thread which is aggregate to this EventThread.
`void`	`notifyTimer()` Wakes up the `runTimer` queue to execute delayed requests.
`boolean`	`removeFromQueue(java.util.EventObject ev)` Removes this event from its queue if it is in the event queue.
`boolean`	`removeTimeEntry(TimeOrder order)` Removes a time order, which was activated but it is not in the event execution queue.
`void`	`setStdEventProcessor(EventConsumer eventProcessor)` Sets the event processor for all events which are not type of `EventWithDst`.
`void`	`start()` Creates and starts the thread.
`private void`	`startOrNotify()`
`protected int`	`stepThread()` The core run routine for the timer thread.
`boolean`	`storeEvent(java.util.EventObject ev)` Stores an event in the queue, able to invoke from any thread.
`java.lang.String`	`toString()`
`protected void`	`wakeup_()` Wakes up the waiting thread because a new event or time entry is enqueues.

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, license and history.
    - 2023-07-14 chg: timeSleep from 10 s to 1 s, elsewhere too much for wait of end.
    - 2023-02-09 new: regard TimeOrder.bHoldTimeorder to change data in time order, prevent processing.
    - 2023-02-09 Operations with TimeOrder now synchronized, some fine refactoring.
    - 2023-02-06 An inheritance of this class is used for org.vishia.gral.base.GralMng as graphic thread. Hence some stuff is now protected, only a few operations are overridden, see there. All non overridden operations are set to final now here.
    - 2023-01-31 The delayMax now also valid if no time order was processed. Before, it was 1000 days. This is not problematically for event processing, because an event wakes up the wait by runTimer.Object.notify() but it is stupid on debugging.
    - 2022-09-24 Some comments and changed while searching the problem that the execution sometimes hangs. But no functionality changes.
    - 2015-05-03 Hartmut new: possibility to check isBusy()
    - 2015-01-10 Hartmut chg: Better algorithm with timeCheckNew
    - 2015-01-10 Hartmut renamed from OrderListExecuter
    - 2014-02-23 Hartmut created: The algorithm is copied from org.vishia.gral.base.GralGraphicThread, this class is the base class of them now. The algorithm is able to use outside of that graphic too.
    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
  - debugPrint
```
private int debugPrint
```
    Bit variable to control some System.out.printf debug outputs.
  - debugPrintViewDelayed
```
int debugPrintViewDelayed
```
    Only for inspector or debug access: Use it to show delaying.
  - threadName
```
protected final java.lang.String threadName
```
  - threadTimer
```
protected java.lang.Thread threadTimer
```
    The thread which executes delayed wake up.
  - eventProcessor
```
private EventConsumer eventProcessor
```
  - queueEvents
```
private final java.util.concurrent.ConcurrentLinkedQueue<java.util.EventObject> queueEvents
```
    Queue of orders which are executed with delay yet.
  - queueDelayedOrders
```
private final java.util.concurrent.ConcurrentLinkedQueue<TimeOrder> queueDelayedOrders
```
    Queue of orders which are executed with delay yet.
  - queueOrdersToExecute
```
private final java.util.concurrent.ConcurrentLinkedQueue<TimeOrder> queueOrdersToExecute
```
    Temporary used instance for orders ready to execute while runTimer organizes the delayed orders. This queue is empty outside running one step of runTimer().
  - bThreadRun
```
protected boolean bThreadRun
```
  - delayMax
```
private int delayMax
```
    The delay [ms] for one step if nothing is to do. It is a proper time also for debugging to see what's happen. Can modified, maybe also 1000 ms
  - timeCheckNew
```
protected long timeCheckNew
```
    timestamp for a new time entry. It is set in synchronized operation between #addTimeOrder(TimeEvent, long) and the wait in the #run() operation. The default value is 10 seconds after now, because no time order may be added. 10 sec is the limited delay to run one step.
  - timeSleep
```
private long timeSleep
```
    The time on start waiting
  - stateThreadTimer
```
protected char stateThreadTimer
```
    State of the thread, used for debug and mutex mechanism. This variable is set 'W' under mutex while the timer waits. Then it should be notified in addTimeEntry(TimeOrder) with delayed order.
  - extEventSet
```
private final java.util.concurrent.atomic.AtomicBoolean extEventSet
```
    Set if any external event is set. Then the dispatcher shouldn't sleep after finishing dispatching. This is important if the external event occurs while the GUI is busy in the operation-system-dispatching loop.
  - startOnDemand
```
protected boolean startOnDemand
```
  - ctWaitEmptyQueue
```
private int ctWaitEmptyQueue
```
  - maxCtWaitEmptyQueue
```
protected int maxCtWaitEmptyQueue
```
  - preserveRecursiveInfoAppend
```
private boolean preserveRecursiveInfoAppend
```
  - runTimer
```
private java.lang.Runnable runTimer
```
    Instance as Runnable contains invocation of stepThread() and the Object.wait() with the calculated timeWait. Note desired for overridden implementation.
- Constructor Detail
  - EventTimerThread
```
public EventTimerThread(java.lang.String threadName)
```
    Creates the Manager for time orders. It is necessary to invoke start() at begin and close() on end of an application.
    
    Parameters:
    
    executesTheOrder - true then the method #step(int, long) need not be called (not necessary) because the TimeOrder are executed from the threadTimer already.
    false then the #step(int, long) have to be called cyclically from any other thread.
- Method Detail
  - setStdEventProcessor
```
public final void setStdEventProcessor(EventConsumer eventProcessor)
```
    Sets the event processor for all events which are not type of EventWithDst. That events are executed with the given eventProcessor's method EventConsumer.processEvent(EventObject). This eventProcessor is not used for EventWithDst. They need a destination or they should be a TimeOrder.
    This routine should be invoked usual one time before start. But the changing of the eventProcessor is possible.
    
    Parameters:
    
    eventProcessor - the event processor.
  - start
```
public final void start()
```
    Creates and starts the thread. If this routine is called from the user, the thread runs till the close() method was called. If this method is not invoked from the user, the thread is created and started automatically if #storeEvent(EventCmdtype) was called. In that case the thread stops its execution if the event queue is empty and about 5 seconds are gone.
  - createThread_
```
protected void createThread_()
```
    This operation can be overridden if another thread organization, especially another stepThread() should be used. Then just another Runnable implementation for the thread is used.
  - storeEvent
```
public final boolean storeEvent(java.util.EventObject ev)
```
    Stores an event in the queue, able to invoke from any thread.
    
    Specified by:
    
    storeEvent in interface EventThread_ifc
    
    Parameters:
    
    ev -
    
    Returns:
    
    false if the event is not stored, because for example it is already stored. true if stored.
  - startOrNotify
```
private void startOrNotify()
```
  - wakeup_
```
protected void wakeup_()
```
    Wakes up the waiting thread because a new event or time entry is enqueues.
    This operation can be overridden for another thread organization. especially in org.vishia.gral.base.GralMng.
  - close
```
public void close()
```
    Should only be called on end of the whole application to finish the timer thread. This method does not need to be called if a @link ConnectionExecThread is given as Argument of @link EventTimerThread#TimeOrderMng(ConnectionExecThread) and this instance implements the @link ConnectionExecThread#isRunning() method. If that method returns false then the timer thread is finished too.
    This operation can be overridden for another thread organization.
    
    Specified by:
    
    close in interface java.io.Closeable
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    See Also:
    
    Closeable.close()
  - addTimeEntry
```
public final char addTimeEntry(TimeOrder order)
```
    Description copied from interface: EventTimerThread_ifc
    
    Adds a timeout event or a time order with given execution time. The time should be set in the event already using its method TimeOrder.activateAt(long) etc. That routines calls this method internally already. Therefore this method should not be called by an application directly. It is only a rule to implement.
    
    Specified by:
    
    addTimeEntry in interface EventTimerThread_ifc
    
    Returns:
    
    a character only for test:
    'n' notified, an earlier time.
    'b' timer thread is yet busy, not notified
    'l' time is later, not notified
    'x' time is expired, executed yet
  - removeTimeEntry
```
public final boolean removeTimeEntry(TimeOrder order)
```
    Removes a time order, which was activated but it is not in the event execution queue. If the time order is expired and it is in the event execution queue already, it is not removed. This operation is thread safe. Either the event is found and removed, or it is not found because it is either in execution yet or it is not queued. The event queue is a ConcurrentLinkedQueue.
    
    Specified by:
    
    removeTimeEntry in interface EventTimerThread_ifc
    
    Parameters:
    
    order -
  - removeFromQueue
```
public final boolean removeFromQueue(java.util.EventObject ev)
```
    Removes this event from its queue if it is in the event queue. If the element of type EventWithDst is found in the queue, it is designated with stateOfEvent = 'a' This operation is thread safe. Either the event is found and removed, or it is not found because it is either in execution yet or it is not queued. The event queue is a ConcurrentLinkedQueue.
    
    Specified by:
    
    removeFromQueue in interface EventThread_ifc
    
    Parameters:
    
    ev - The event which should be dequeued
    
    Returns:
    
    true if found.
  - isBusy
```
public boolean isBusy()
```
    Description copied from interface: EventThread_ifc
    
    Checks whether the thread is busy. This is used especially for debug, if a TimeOrder waits for its finishing. If an execution remains in process because debugging, this method returns true.
    
    Specified by:
    
    isBusy in interface EventThread_ifc
    
    Returns:
  - checkEventAndRun
```
private boolean checkEventAndRun()
```
    Applies an events from the queue to the destination in the event thread.
    
    Returns:
    
    true if any action was done because an event was found. false if the queue is empty.
  - checkTimeOrders
```
private int checkTimeOrders()
```
    Check all time orders whether there are expired, or if not calculate the next time to check. This operation runs under mutex in that part which changes TimeOrders and the queueDelayedOrders regarding changing also for and because TimeOrder.activateAt(long, long), which uses this as mutex.
    
    If a TimeOrder is expired:
    If the #evDst() is given the EventConsumer.processEvent(java.util.EventObject) is called though this instance may be a timeOrder. This method can enqueue this instance in another queue for execution in any other thread which invokes then TimeOrder#doExecute().
    It this is a TimeOrder and the #evDst is not given by constructor then the TimeOrder#doExecute() is called to execute the time order.
    If this routine is started then an invocation of #activate(int) etc. enqueues this instance newly with a new time for elapsing. It is executed newly therefore.
    
    Returns:
    
    the delay time in ms.
  - stepThread
```
protected final int stepThread()
```
    The core run routine for the timer thread. The timer thread is in an delay till
    
    Returns:
    
    time to wait.
  - isCurrentThread
```
public final boolean isCurrentThread()
```
    Returns true if the current thread is the thread which is aggregate to this EventThread. It means the #run() method has called this method.
    
    Specified by:
    
    isCurrentThread in interface EventThread_ifc
    
    Returns:
    
    false if a statement in another thread checks whether this EventThread runs.
  - getState
```
public final char getState()
```
    Returns the current state of the thread.
    - ?: Thread never started
    - c: executes an order
    - W: waits, don't have the processor
    - f: finished
  - notifyTimer
```
public void notifyTimer()
```
    Wakes up the runTimer queue to execute delayed requests.
    This operation can be overridden for another thread organization.
  - infoAppend
```
public java.lang.CharSequence infoAppend(java.lang.StringBuilder u)
```
    Info for debugging
    This operation can be overridden for another thread organization.
    
    Specified by:
    
    infoAppend in interface InfoAppend
    
    Parameters:
    
    u - if not null then the info is appended to u, u is returned.
    if null then a String can be returned if it is sufficient.
    
    Returns:
    
    u if given or a new StringBuilder instance which contains the info or a String if it is sufficient.
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class EventTimerThread

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

version

debugPrint

debugPrintViewDelayed

threadName

threadTimer

eventProcessor

queueEvents

queueDelayedOrders

queueOrdersToExecute

bThreadRun

delayMax

timeCheckNew

timeSleep

stateThreadTimer

extEventSet

startOnDemand

ctWaitEmptyQueue

maxCtWaitEmptyQueue

preserveRecursiveInfoAppend

runTimer

Constructor Detail

EventTimerThread

Method Detail

setStdEventProcessor

start

createThread_

storeEvent

startOrNotify

wakeup_

close

addTimeEntry

removeTimeEntry

removeFromQueue

isBusy

checkEventAndRun

checkTimeOrders

stepThread

isCurrentThread

getState

notifyTimer

infoAppend

toString