Mastering Thread Coordination: Waiters, Rendezvous, Joiners in Java

Thread Coordination Operations

The Helper class supplies a suite of built‑in operations designed to simplify complex testing and synchronization in multi‑threaded applications. These operations are divided into three categories: thread coordination, rule‑state management, and tracing/debugging. The following sections focus on the coordination primitives.

1. Waiters

Waiters allow a thread to suspend execution during rule evaluation and be resumed or aborted by other threads. Unlike Object.wait(), the suspension is managed internally by the Helper class using private Waiter objects, avoiding interference with external locking.

public void waitFor(Object identifier)
public void waitFor(Object identifier, long millisecsWait)
public boolean waiting(Object identifier)
public boolean signalWake(Object identifier)
public boolean signalWake(Object identifier, boolean mustMeet)
public boolean signalThrow(Object identifier)
public boolean signalThrow(Object identifier, boolean mustMeet)

waitFor : Called from a rule action; pauses the current thread until signalWake or signalThrow is invoked on the same identifier. The version without a timeout never times out; the timed version aborts after the specified milliseconds.

waiting : Used in rule conditions; returns true if any thread is waiting on the given identifier, otherwise false.

signalWake : Used in conditions or actions; wakes waiting threads and returns true if a thread was awakened, otherwise false. The optional mustMeet parameter forces the signaling thread to wait until at least one waiter is present when set to true.

signalThrow : Similar to signalWake but also causes waiting threads to throw an ExecuteException from their trigger‑method framework. It accepts the same optional mustMeet flag.

2. Rendezvous (Collection Points)

Rendezvous provide symmetric synchronization, allowing a set of threads to meet at a point without a predefined master‑slave relationship. Threads are ordered by arrival, and the first (or last) arriving thread can be identified for further actions.

public boolean createRendezvous(Object identifier, int expected)
public boolean createRendezvous(Object identifier, int expected, boolean rejoinable)
public boolean rendezvous(Object identifier)
public boolean rendezvous(Object identifier, long timeout)
public boolean isRendezvous(Object identifier, int expected)
public int getRendezvous(Object identifier, int expected)
public int deleteRendezvous(Object identifier, int expected)

createRendezvous : Creates a rendezvous identified by identifier. expected specifies how many threads must arrive before they are released. If rejoinable is true, the rendezvous resets after the first batch, allowing subsequent rounds.

rendezvous : Called by a thread to wait at the rendezvous. If the number of arrived threads is less than expected, the caller blocks; otherwise all blocked threads are released. A timeout variant throws a runtime exception if the wait exceeds the given milliseconds. Zero or negative timeout disables the timeout.

isRendezvous : Returns true when a rendezvous with the given identifier exists and has the expected count; otherwise false.

getRendezvous : Returns the current number of threads waiting at the rendezvous, or 0 if none are waiting. Returns -1 if the rendezvous does not exist or has a mismatched expected count.

deleteRendezvous : Removes the rendezvous, breaking the association with its identifier. Any threads blocked in rendezvous receive a return value of -1. Returns true on successful deletion, false otherwise.

3. Joiners

Joiners are useful when a thread must wait for one or more related threads to finish before proceeding. They complement the standard Thread.join() by allowing dynamic registration of participating threads.

public boolean createJoin(Object identifier, int expected)
public boolean isJoin(Object identifier, int expected)
public boolean joinEnlist(Object identifier)
public boolean joinWait(Object identifier, int expected)
public boolean joinWait(Object identifier, int expected, long timeout)

createJoin : Creates a Joiner identified by identifier with an expected count of threads that must join. Returns true on success, false if a Joiner with the same identifier already exists.

isJoin : Checks whether a Joiner with the given identifier and expected count exists.

joinEnlist : Adds the calling thread to the Joiner’s internal thread list. Returns true if the thread was added; false if the identifier is unknown or the expected count has already been reached.

joinWait : Blocks the calling thread until the number of enlisted threads reaches expected. An optional timeout variant throws a runtime exception if the wait exceeds the timeout; zero or negative timeout disables the timeout.

4. Abort Execution

The Helper class also provides two built‑in actions that can abort the execution of a rule’s trigger method.

public void killThread()
public void killJVM()
public void killJVM(int exitCode)

killThread : Throws an ExecuteException inside the trigger‑method framework, effectively terminating the current thread unless caught by a global exception handler.

killJVM : Calls java.lang.Runtime.getRuntime().halt(), instantly halting the JVM without invoking shutdown hooks. If exitCode is omitted, it defaults to -1.