LooperThread (j(s)-lib Commons 1.3.0 API)

java.lang.Object
- js.lang.LooperThread

All Implemented Interfaces:

Runnable
```
public class LooperThread
extends Object
implements Runnable
```
Thread that executes Looper.loop() with optional iteration period. Looper thread has convenient methods to start and stop thread execution and supports two iteration modes: continuous and periodic.
In continuous mode looper thread executes loop iterations with processor speed. Looper instance is usually waiting for some IO, takes care itself to sleep for some time or really has much computation to do. It is looper instance responsibility to ensure processor is not abused.
To enable periodic mode one should use a constructor that supplies a period value. Looper thread executes internal sleep and invoke iteration with requested period. Implementation takes care to compensate for iteration processing time but if it takes more that requested period looper thread works again in continuous mode.
In any case, looper implementation should consider that thread checks for running state between loops - for this reason blocking read operations are not allowed.
For your convenience here is a sample code.
```
 class DemoLooper implements Looper, AsyncExceptionListener
 {
   private LooperThread thread;
 
   DemoLooper()
   {
     tread = new LooperThread(this);
     thread.start();
   }
 
   void stop()
   {
     thread.stop();
   }
 
   void loop() throws Exception
   {
     // execute iteration logic
   }
 
   void onAsyncException(Throwable throwable)
   {
     // handle loop iteration exception
   }
 }
 
```
Since looper is running in a separated thread is not possible to catch exceptions. If interested in handling loop iteration exception one should make looper implementing AsyncExceptionListener. It is also possible to set exception listener after looper thread creation, even after thread start, using setExceptionListener(AsyncExceptionListener).
Looper thread runs till explicit stop(). This is true even if a loop execution throws exception; default behavior is to dump stack and continue loop iterations. Anyway, if desirable to break the loop on exception one can use setBreakOnException(boolean) to set breakOnException flag to true.
Version:

final

Author:

Iulian Rotaru

Field Summary

Fields
Modifier and Type	Field and Description
`private AtomicBoolean`	`breakOnException` break thread looper on exception, default to false.
`private static int`	`EXCEPTION_TIMEOUT` If looper thread works in `continuous` mode add a timeout on exception loop in order to avoid hogging the thread.
`private AsyncExceptionListener`	`exceptionListener` Asynchronous exception listener.
`private long`	`exceptionTimestamp` Keep track of the previous exception in order to prevent exceptions to occur to often.
`private static Log`	`log` Class logger.
`private Looper`	`looper` Looper instance to invoke repetitively.
`private int`	`loopPeriod` Optional loop iteration period in milliseconds.
`private AtomicBoolean`	`running` Running state.
`private static int`	`SAMPLING_PERIOD` Looper tests `running` flag with this sampling period, expressed in milliseconds.
`private static int`	`STARTUP_TIMEOUT` Looper thread start-up timeout.
`private static int`	`STOP_TIMEOUT` Looper thread stop timeout.
`private Thread`	`thread` Underlying Java Thread.

Constructor Summary

Constructors
Constructor and Description
`LooperThread(Looper looper)` Create looper thread.
`LooperThread(Looper looper, int period)` Create looper thread with iteration period.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`isRunning()` Return true if this looper thread is running.
`void`	`join(long millis)` Waits at most millis milliseconds for this thread to die.
`void`	`run()`
`void`	`setBreakOnException(boolean breakOnException)` Set flag for breaking looper on exception.
`void`	`setExceptionListener(AsyncExceptionListener exceptionListener)` Set asynchronous exception listener to handle loop exceptions.
`private static void`	`sleep(long period)` Interruptible thread sleep.
`void`	`start()` Start the thread and wait for its actual startup.
`void`	`stop()` Stop thread and waits for its graceful close.
`private static void`	`wait(Object lock, int timeout)` Wait notification on synchronized object for specified period of time.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - log
```
private static final Log log
```
    Class logger.
  - STARTUP_TIMEOUT
```
private static final int STARTUP_TIMEOUT
```
    Looper thread start-up timeout.
    
    See Also:
    
    Constant Field Values
  - STOP_TIMEOUT
```
private static final int STOP_TIMEOUT
```
    Looper thread stop timeout. If this timeout exceeds stop() method returns without ensuring thread graceful close. Note that Looper.loop() processing duration should not exceed this timeout.
    
    See Also:
    
    Constant Field Values
  - EXCEPTION_TIMEOUT
```
private static final int EXCEPTION_TIMEOUT
```
    If looper thread works in continuous mode add a timeout on exception loop in order to avoid hogging the thread.
    
    See Also:
    
    Constant Field Values
  - SAMPLING_PERIOD
```
private static final int SAMPLING_PERIOD
```
    Looper tests running flag with this sampling period, expressed in milliseconds. Anyway, if loop period is smaller uses it instead.
    
    See Also:
    
    Constant Field Values
  - thread
```
private final Thread thread
```
    Underlying Java Thread.
  - looper
```
private final Looper looper
```
    Looper instance to invoke repetitively.
  - loopPeriod
```
private final int loopPeriod
```
    Optional loop iteration period in milliseconds.
  - running
```
private final AtomicBoolean running
```
    Running state.
  - breakOnException
```
private final AtomicBoolean breakOnException
```
    break thread looper on exception, default to false.
  - exceptionListener
```
private volatile AsyncExceptionListener exceptionListener
```
    Asynchronous exception listener.
  - exceptionTimestamp
```
private long exceptionTimestamp
```
    Keep track of the previous exception in order to prevent exceptions to occur to often. It is used only in continuous mode, that is, period is zero.
- Constructor Detail
  - LooperThread
```
public LooperThread(Looper looper)
```
    Create looper thread. If looper instance implements AsyncExceptionListener it is also registered as exception listener.
    
    Parameters:
    
    looper - looper instance.
  - LooperThread
```
public LooperThread(Looper looper,
                    int period)
```
    Create looper thread with iteration period. Iteration period is expressed in milliseconds and should be positive; if zero looper thread is configured in continuous mode. If looper instance implements AsyncExceptionListener it is also registered as exception listener.
    
    Parameters:
    
    looper - looper instance,
    
    period - loop iteration period, in milliseconds, possible zero.
    
    Throws:
    
    IllegalArgumentException - if looper instance is null or period is not positive or zero.
- Method Detail
  - setBreakOnException
```
public void setBreakOnException(boolean breakOnException)
```
    Set flag for breaking looper on exception. See class description for a discussion about exception handling.
    
    Parameters:
    
    breakOnException - break on exception flag.
  - setExceptionListener
```
public void setExceptionListener(AsyncExceptionListener exceptionListener)
```
    Set asynchronous exception listener to handle loop exceptions. If given argument is null remove current exception lister. See class description for a discussion about exception handling.
    
    Parameters:
    
    exceptionListener - asynchronous exception listener, possible null.
    
    See Also:
    
    exceptionListener
  - start
```
public void start()
```
    Start the thread and wait for its actual startup.
  - stop
```
public void stop()
```
    Stop thread and waits for its graceful close. Please note that if STOP_TIMEOUT exceeds this method does not guarantee graceful thread close.
    If thread is not alive, see Thread.isAlive(), this method does nothing.
  - isRunning
```
public boolean isRunning()
```
    Return true if this looper thread is running.
    
    Returns:
    
    true if looper thread is running.
  - run
```
public void run()
```
    Specified by:
    
    run in interface Runnable
  - join
```
public void join(long millis)
          throws InterruptedException
```
    Waits at most millis milliseconds for this thread to die. A timeout of 0 means to wait forever.
    
    Parameters:
    
    millis - the time to wait in milliseconds.
    
    Throws:
    
    InterruptedException - if any thread has interrupted the current thread. The interrupted status of the current thread is cleared when this exception is thrown.
  - wait
```
private static void wait(Object lock,
                         int timeout)
```
    Wait notification on synchronized object for specified period of time. If timeout is zero this method blocks till notification arrive.
    
    Parameters:
    
    lock - synchronized object to wait on, possible zero,
    
    timeout - timeout in milliseconds.
  - sleep
```
private static void sleep(long period)
```
    Interruptible thread sleep.
    
    Parameters:
    
    period - thread sleep period.

Class LooperThread

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

log

STARTUP_TIMEOUT

STOP_TIMEOUT

EXCEPTION_TIMEOUT

SAMPLING_PERIOD

thread

looper

loopPeriod

running

breakOnException

exceptionListener

exceptionTimestamp

Constructor Detail

LooperThread

LooperThread

Method Detail

setBreakOnException

setExceptionListener

start

stop

isRunning

run

join

wait

sleep