public final class EventSemaphore extends RelatedResource
The idea here is to provide the capability of posting (or raising) a signal which can be
waited on by other threads. An event semaphore has two possible states: reset (the event
has not been signaled) and posted (the event has occurred). Threads call await
to
wait for the event to be posted.
reset
is used to move the semaphore into reset state and post
is used to
move the semaphore into posted state.
await
will return immediately if the semaphore is already posted, but it will block
if the semaphore is in reset state. All waiting threads are released at the moment that
the semaphore shifts from reset into posted state. If the semaphore is reset after posting
and a thread that was waiting before the post occurred does not run before the reset happens,
that thread will still be released and it will still be runnable. In other words, this
mechanism is "edge triggered" and is NOT "level" based.
The await
method has a form that waits indefinitely and a second form that takes a
timeout value in milliseconds. Upon return from await
a status enum is returned.
There are 4 ways to exit await (posted, timeout, interrupted, semaphore destroyed).
If you need to check to see if the await
will block, you may call query
to
read the posted count. WARNING: there is no guarantee that the state will remain the same
after the call to query
returns.
Modifier and Type | Field and Description |
---|---|
private int |
posted
Number of times this semaphore has been posted.
|
private static java.lang.String |
RESOURCE_TYPE
Unique resource type name, used as a namespace prefix.
|
active, lock, name
BIT_CREATE_ACCESS, BIT_DELETE_ACCESS, BIT_DENIED_ACCESS, BIT_READ_ACCESS, BIT_WRITE_ACCESS, BITSET_SIZE
Modifier | Constructor and Description |
---|---|
private |
EventSemaphore(java.lang.String name)
Disable external construction.
|
Modifier and Type | Method and Description |
---|---|
WaitStatus |
await()
Block until the semaphore is posted (if the semaphore is current reset) and if the
semaphore is already posted at the time this is called, then return immediately.
|
WaitStatus |
await(long millis)
Block until the semaphore is posted (if the semaphore is current reset) OR until the
specified number of milliseconds has elapsed, whichever comes first.
|
static EventSemaphore |
create(java.lang.String name)
Factory method which creates a new local event semaphore with the given name.
|
static EventSemaphore |
create(java.lang.String name,
boolean reset)
Factory method which creates a new local event semaphore with the given name.
|
static EventSemaphore |
create(java.lang.String name,
boolean reset,
boolean local)
Factory method which creates a new event semaphore with the given name.
|
static EventSemaphore |
open(java.lang.String name)
Opens an existing local event semaphore with the given name.
|
static EventSemaphore |
open(java.lang.String name,
boolean local)
Opens an existing local event semaphore with the given name.
|
void |
post()
Increase the posted count by 1 and if the old posted count was 0, release all waiting
threads.
|
int |
query()
Return the number of times the semaphore has been posted since the last reset.
|
int |
reset()
Reset the posted count and return the old count value.
|
java.lang.String |
resourceName()
Obtain the resource name (which makes up the prefix for valid names of this resource type).
|
checkAccess, checkDelete, checkName, checkRead, checkWrite, close, create, destroy, errorIfDead, formatName, open, release, status
private static final java.lang.String RESOURCE_TYPE
private int posted
private EventSemaphore(java.lang.String name)
name
- Resource name, must not be null
.public static EventSemaphore create(java.lang.String name) throws ErrorConditionException
name
- The semaphore name, without the standard "/event_semaphore/" prefix.ErrorConditionException
- If there was any problem in creation.public static EventSemaphore create(java.lang.String name, boolean reset) throws ErrorConditionException
name
- The semaphore name, without the standard "/event_semaphore/" prefix.reset
- true
to set the state to reset at creation, false
to set the
initial state to posted.ErrorConditionException
- If there was any problem in creation.public static EventSemaphore create(java.lang.String name, boolean reset, boolean local) throws ErrorConditionException
name
- The semaphore name, without the standard "/event_semaphore/" prefix.reset
- true
to set the state to reset at creation, false
to set the
initial state to posted.local
- true
to create a local instance (one that is only accessible between
threads in the same security context. false
creates an instance that
is accessible from any session in the JVM.ErrorConditionException
- If there was any problem in creation.public static EventSemaphore open(java.lang.String name) throws ErrorConditionException
name
- The semaphore name, without the standard "/event_semaphore/" prefix.ErrorConditionException
- If there was any problem in opening.public static EventSemaphore open(java.lang.String name, boolean local) throws ErrorConditionException
name
- The semaphore name, without the standard "/event_semaphore/" prefix.local
- true
to open a local instance (one that is only accessible between
threads in the same security context. false
opens an instance that
is accessible from any session in the JVM.ErrorConditionException
- If there was any problem in opening.public java.lang.String resourceName()
resourceName
in class RelatedResource
public void post() throws ErrorConditionException
ErrorConditionException
- If the semaphore is destroyed or if there is an access rights issue.public WaitStatus await() throws ErrorConditionException
This version of the waiting will not time out.
ErrorConditionException
- If the semaphore is destroyed or if there is an access rights issue.public WaitStatus await(long millis) throws ErrorConditionException
millis
- Maximum wait time, use 0 or any negative number for an indefinite wait.ErrorConditionException
- If the semaphore is destroyed or if there is an access rights issue.public int reset() throws ErrorConditionException
ErrorConditionException
- If the semaphore is destroyed or if there is an access rights issue.public int query() throws ErrorConditionException
This can be used to detect if a call to await
would block AT THIS INSTANT.
WARNING: there is no guarantee that the state will remain the same after the
call to returns, so an immediate call to await
will block if the semaphore
is reset
in between the query
and await
calls.
ErrorConditionException
- If the semaphore is destroyed or if there is an access rights issue.