Package org.jcsp.lang

# Class CSTimer

java.lang.Object
org.jcsp.lang.Guard
org.jcsp.lang.CSTimer

public class CSTimer extends Guard
This is a `Guard` for setting timeouts in an `Alternative`.

## Description

`CSTimer` is a `Guard` for setting timeouts in an `Alternative`. It also provides the current system time and can set straight (i.e. committed) timeouts. The timeouts are in terms of absolute time values - not relative delays.

Note: for those familiar with the occam multiprocessing language, `CSTimer` gives the semantics of the `TIMER` type (including its use as a guard in an `ALT` construct).

Warning: a `CSTimer` records the timeout value for use by an `Alternative`. Therefore, different `CSTimer`s must be used by different processes - the same `CSTimer` must not be shared.

Implementation note: all `CSTimer` s currently use the same `System.currentTimeMillis` time.

## Examples

The use of a `CSTimer` for setting timeouts on channel input is documented in the `Alternative` class (see the examples A Fair Multiplexor with a Timeout and A Simple Traffic Flow Regulator).

Here, we just show its use for setting committed timeouts. `Regular` generates a regular stream of output on its `out` channel. The rate of output is determined by its `interval` parameter. Recall that timeouts implemented by `CSTimer` are in terms of absolute time values. Notice that the sequence of output times maintains an arithmetic progression. Any delays in completing each cycle (e.g. caused by the process scheduler or the lateness of the process synchronising with us to accept our data) will be compensated for automatically - the output sequence always returns to its planned schedule whenever it can.

     import org.jcsp.lang.*;

     public class Regular implements CSProcess {

       final private ChannelOutput out;
       final private Integer N;
       final private long interval;

       public Regular (final ChannelOutput out, final int n, final long interval) {
         this.out = out;
         this.N = new Integer (n);
         this.interval = interval;
       }

       public void run () {

         final CSTimer tim = new CSTimer ();
         long timeout = tim.read ();       // read the (absolute) time once only

         while (true) {
           out.write (N);
           timeout += interval;            // set the next (absolute) timeout
           tim.after (timeout);            // wait until that (absolute) timeout
         }
       }

     }

For convenience, a ``sleep`` method that blocks for a specified time period (in milliseconds) is also provided. This has the same semantics as ``java.lang.Thread.sleep``. [Note: programming a regular sequence of events is a little easier using ``after`` (as in the above) rather than ``sleep``.]

Author:
  P.D. Austin, P.H. Welch
See Also:
  - `Alternative`
  - `Guard`

## Constructor Summary

Constructors
Constructor
Description
`CSTimer()`

## Method Summary

Modifier and Type
Method
Description
`void`
`after(long msecs)`
Puts the process to sleep until an absolute time is reached.
`long`
`getAlarm()`
Returns the alarm value that has been set by the previous call to `setAlarm(long)`.
`long`
`read()`
Returns the current system time in msecs.
`void`
`set(long msecs)`
Deprecated.
Use `setAlarm(long)` - this name caused confusion with the idea of setting the current time (a concept that is not supported).
`void`
`setAlarm(long msecs)`
Sets the absolute timeout value that will trigger an `Alternative` select operation (when this `CSTimer` is one of the guards with which that `Alternative` was constructed).
`void`
`sleep(long msecs)`
Puts the process to sleep for a specified time (milliseconds).

### Methods inherited from class org.jcsp.lang.Guard

`schedule`

### Methods inherited from class java.lang.Object

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

## Constructor Details

### CSTimer

public CSTimer()

## Method Details

### setAlarm

public void setAlarm(long msecs)
Sets the absolute timeout value that will trigger an `Alternative` select operation (when this `CSTimer` is one of the guards with which that `Alternative` was constructed).

Parameters:
  `msecs` - the absolute timeout value.

### getAlarm

public long getAlarm()
Returns the alarm value that has been set by the previous call to `setAlarm(long)`.

### set

public void set(long msecs)
Deprecated.
Use `setAlarm(long)` - this name caused confusion with the idea of setting the current time (a concept that is not supported).
Sets the absolute timeout value that will trigger an `Alternative` select operation (when this `CSTimer` is one of the guards with which that `Alternative` was constructed).

Parameters:
  `msecs` - the absolute timeout value.

### read

public long read()
Returns the current system time in msecs.

Returns:
  the current system time in msecs

### after

public void after(long msecs)
Puts the process to sleep until an absolute time is reached.

Parameters:
  `msecs` - the absolute time awaited. Note: if this time has already been reached, this returns straight away.

### sleep

public void sleep(long msecs)
Puts the process to sleep for a specified time (milliseconds).

Parameters:
  `msecs` - the length of the sleep period. Note: if this is negative, this returns straight away.