jdk.dio.counter

Interface PulseCounter

All Superinterfaces:

java.lang.AutoCloseable, java.nio.channels.Channel, java.io.Closeable, Device<PulseCounter>

public interface PulseCounter
extends Device<PulseCounter>

The PulseCounter interface provides methods for controlling a pulse counter. A pulse counter can count pulses (or events) on a digital input line (possibly a GPIO pin).

A pulse counter may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. A PulseCounter instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a PulseCounter instance is opened with an ad-hoc PulseCounterConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

Once opened, an application can either start a pulse counting session using the startCounting method and retrieve the current pulse count on-the-fly by calling the getCount method; or it can start a pulse counting session with a terminal count value and a counting time interval using the startCounting(int, long, jdk.dio.counter.CountingListener) and get asynchronously notified once the terminal count value has been reached or the counting time interval has expired. In both cases, the application can retrieve the current pulse count at any time (on-the-fly) by calling the getCount.

The pulse counting session can be suspended by calling suspendCounting and later on resumed from its previous count value by calling resumeCounting. Suspending the pulse counting also suspends the session counting time interval timer if active.

The pulse count value can be reset at any time during counting by calling resetCounting. This also resets the session counting time interval timer if active.

Finally, the pulse counting can be stopped by calling stopCounting.

When an application is no longer using a pulse counter it should call the close method to close the pulse counter. Any further attempt to use a pulse counter which has been closed will result in a ClosedDeviceException been thrown.

Note that asynchronous notification of pulse counting conditions is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic/timely manner.

See Also:

CountingListener, CounterPermission

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
int	getCount() Gets the pulse count measured so far during the current (if still active) or previous counting session.
void	resetCounting() Resets the current count value.
void	resumeCounting() Resumes the counting starting from the frozen count value.
void	startCounting() Starts a pulse counting session.
void	startCounting(int limit, long interval, CountingListener listener) Starts an asynchronous pulse counting session.
void	stopCounting() Stops the pulse counting and freezes the current count value.
void	suspendCounting() Suspends the pulse counting and freezes the current count value.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Method Detail

getCount

int getCount()
             throws java.io.IOException,
                    UnavailableDeviceException,
                    ClosedDeviceException

Gets the pulse count measured so far during the current (if still active) or previous counting session.

Returns:

the pulse count measured so far during the current or previous counting session; 0 is returned if none has been measured so far.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

resetCounting

void resetCounting()
                   throws java.io.IOException,
                          UnavailableDeviceException,
                          ClosedDeviceException

Resets the current count value.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if counting is not active.

resumeCounting

void resumeCounting()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Resumes the counting starting from the frozen count value.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if counting is not active.

startCounting

void startCounting()
                   throws java.io.IOException,
                          UnavailableDeviceException,
                          ClosedDeviceException

Starts a pulse counting session.

The pulse count value is first reset.

If the counter overflows it restarts from 0 without any further notification. To be notified of such conditions the startCounting(int, long, jdk.dio.counter.CountingListener) method should be used instead.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if counting is already active.

startCounting

void startCounting(int limit,
                 long interval,
                 CountingListener listener)
                   throws java.io.IOException,
                          UnavailableDeviceException,
                          ClosedDeviceException

Starts an asynchronous pulse counting session. The provided CountingListener instance will be asynchronously invoked when the pulse count reaches the provided terminal count value or the specified counting time interval expires - whichever happens first.

The pulse count value is first reset and will be reset every time the terminal count value is reached or the counting time interval expires.

If limit is equal to or less than 0 then the counting time interval will end only after the time specified by interval has passed. If interval is equal to or less than 0 then the counting time interval will end only after the pulse count has reached the terminal count value specified by limit. The counting time interval is expressed in microseconds; if the underlying platform does not support a microsecond timer resolution then interval will rounded up to accommodate the supported timer resolution.

Pulse counting and notification will immediately start and will repeat until it is stopped by a call to stopCounting.

Only one pulse counting session can be going on at any time.

Parameters:

listener - the CountingListener instance to be notified when the pulse count reaches the terminal count value.

limit - the terminal count value.

interval - the counting time interval (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if limit and interval are both equal to or less than 0.

java.lang.NullPointerException - if listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if counting is already active.

stopCounting

void stopCounting()
                  throws java.io.IOException,
                         UnavailableDeviceException,
                         ClosedDeviceException

Stops the pulse counting and freezes the current count value. The count value will be reset upon the next start.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

suspendCounting

void suspendCounting()
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Suspends the pulse counting and freezes the current count value.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if counting is not active.