A grouping of threads that typically run closely related tasks. Threads started in a flock remain in the flock until they terminate.

ThreadFlock defines the open method to open a new flock, the start method to start a thread in the flock, and the close method to close the flock. The close waits for all threads in the flock to finish. The awaitAll method may be used to wait for all threads to finish without closing the flock. The wakeup() method will cause awaitAll method to complete early, which can be used to support cancellation in higher-level APIs. ThreadFlock also defines the shutdown method to prevent new threads from starting while allowing existing threads in the flock to continue.

Thread flocks are intended to be used in a structured manner. The thread that opens a new flock is the owner. The owner closes the flock when done, failure to do so may result in a resource leak. The open and close should be matched to avoid closing an enclosing flock while a nested flock is open. A ThreadFlock can be used with the try-with-resources construct if required but more likely, the close method of a higher-level API that implements AutoCloseable will close the flock.

Thread flocks are conceptually nodes in a tree. A thread T started in flock "A" may itself open a new flock "B", implicitly forming a tree where flock "A" is the parent of flock "B". When nested, say where thread T opens flock "B" and then invokes a method that opens flock "C", then the enclosing flock "B" is conceptually the parent of the nested flock "C". ThreadFlock does not define APIs that exposes the tree structure. It does define the containsThread method to test if a flock contains a thread, a test that is equivalent to testing membership of flocks in the tree. The start and shutdown methods are confined to the flock owner or threads contained in the flock. The confinement check is equivalent to invoking the containsThread method to test if the caller is contained in the flock.

Unless otherwise specified, passing a null argument to a method in this class will cause a NullPointerException to be thrown.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	ThreadFlock.ThreadContainerImpl A ThreadContainer backed by a ThreadFlock.

Field Summary

Modifier and Type	Field and Description
private volatile boolean	closed
private final ThreadFlock.ThreadContainerImpl	container
private static final JavaLangAccess	JLA
private final String	name
private static final VarHandle	PERMIT
private volatile boolean	permit
private final ScopedValueContainer.BindingsSnapshot	scopedValueBindings
private volatile boolean	shutdown
private static final VarHandle	THREAD_COUNT
private volatile int	threadCount
private final Set<Thread>	threads

Access	Constructor and Description
pack-priv	ThreadFlock(String name)

Method Summary

Modifier and Type	Method and Description
public boolean	Returns: true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads awaitAll() Wait for all threads in the flock to finish executing their tasks.
public boolean	Returns: true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads awaitAll(Duration the maximum duration to wait timeout) Wait, up to the given waiting timeout, for all threads in the flock to finish executing their tasks.
private void	clearPermit() Clear wakeup permit.
public void	close() Implements java.lang.AutoCloseable.close. Closes this flock.
public boolean	Returns: true if this flock contains the thread containsThread(Thread the thread thread) Tests if this flock contains the given thread.
private void	decrementThreadCount() Decrement the thread count.
private void	ensureOwner() Throws WrongThreadException if the current thread is not the owner.
private void	ensureOwnerOrContainsThread() Throws WrongThreadException if the current thread is not the owner or a thread contained in the flock.
private boolean	getAndSetPermit(boolean newValue) Sets the wakeup permit to the given value, returning the previous value.
private void	incrementThreadCount()
public boolean	Returns: true if the flock has been closed isClosed() Returns true if the flock has been closed.
public boolean	Returns: true if the flock has been shut down isShutdown() Returns true if the flock has been shut down.
public String	Returns: the name of this flock or `null` if unnamed name() Returns the name of this flock or `null` if unnamed.
private void	onExit(Thread thread) Invoked on the terminating thread or the parent thread when starting `thread` failed.
private void	onStart(Thread thread) Invoked on the parent thread when starting `thread`.
public static ThreadFlock	Returns: a new thread flock open(String the name of the flock, can be null name) Opens a new thread flock.
public Thread	Returns: the owner of this flock owner() Returns the owner of this flock.
private ScopedValueContainer.BindingsSnapshot	scopedValueBindings()
public void	shutdown() Shutdown this flock so that no new threads can be started, existing threads in the flock will continue to run.
public Thread	Returns: the thread, started start(Thread the unstarted thread thread) Starts the given unstarted thread in this flock.
private long	threadCount()
public Stream<Thread>	Returns: a stream of the threads in this flock threads() Returns a stream of the threads in this flock.
public String	toString() Overrides java.lang.Object.toString. Returns a string representation of the object.
public void	wakeup() Causes the call to `awaitAll()` or `awaitAll(Duration)` by the owner to return immediately.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll wait wait wait

Field Detail

closed	back to summary
private volatile boolean closed

container	back to summary
private final ThreadFlock.ThreadContainerImpl container

container

back to summary

private final ThreadFlock.ThreadContainerImpl container

JLA	back to summary
private static final JavaLangAccess JLA

name	back to summary
private final String name

PERMIT	back to summary
private static final VarHandle PERMIT

permit	back to summary
private volatile boolean permit

scopedValueBindings	back to summary
private final ScopedValueContainer.BindingsSnapshot scopedValueBindings

shutdown	back to summary
private volatile boolean shutdown

THREAD_COUNT	back to summary
private static final VarHandle THREAD_COUNT

threadCount	back to summary
private volatile int threadCount

threads	back to summary
private final Set<Thread> threads

Constructor Detail

ThreadFlock	back to summary
pack-priv ThreadFlock(String name)

Method Detail

awaitAll back to summary

awaitAll	back to summary
public boolean awaitAll() throws InterruptedException Wait for all threads in the flock to finish executing their tasks. This method waits until all threads finish, the `wakeup` method is invoked, or the current thread is interrupted. This method may only be invoked by the flock owner. The method trivially returns true when the flock is closed. This method clears the effect of any previous invocations of the `wakeup` method. Returns:boolean true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads Exceptions InterruptedException: if interrupted while waiting WrongThreadException: if invoked by a thread that is not the owner

public boolean awaitAll() throws InterruptedException

Wait for all threads in the flock to finish executing their tasks. This method waits until all threads finish, the wakeup method is invoked, or the current thread is interrupted.

This method may only be invoked by the flock owner. The method trivially returns true when the flock is closed.

This method clears the effect of any previous invocations of the wakeup method.

Returns:boolean

true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads

Exceptions

InterruptedException:: if interrupted while waiting
WrongThreadException:: if invoked by a thread that is not the owner

awaitAll back to summary

awaitAll	back to summary
public boolean awaitAll(Duration timeout) throws InterruptedException, TimeoutException Wait, up to the given waiting timeout, for all threads in the flock to finish executing their tasks. This method waits until all threads finish, the `wakeup` method is invoked, the current thread is interrupted, or the timeout expires. This method may only be invoked by the flock owner. The method trivially returns true when the flock is closed. This method clears the effect of any previous invocations of the `wakeup` method. Parameters timeout:Duration the maximum duration to wait Returns:boolean true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads Exceptions InterruptedException: if interrupted while waiting TimeoutException: if the wait timed out WrongThreadException: if invoked by a thread that is not the owner

public boolean awaitAll(Duration timeout) throws InterruptedException, TimeoutException

Wait, up to the given waiting timeout, for all threads in the flock to finish executing their tasks. This method waits until all threads finish, the wakeup method is invoked, the current thread is interrupted, or the timeout expires.

This method may only be invoked by the flock owner. The method trivially returns true when the flock is closed.

This method clears the effect of any previous invocations of the wakeup method.

Parameters

timeout:Duration: the maximum duration to wait

Returns:boolean

true if there are no threads in the flock, false if wakeup was invoked and there are unfinished threads

Exceptions

InterruptedException:: if interrupted while waiting
TimeoutException:: if the wait timed out
WrongThreadException:: if invoked by a thread that is not the owner

clearPermit	back to summary
private void clearPermit() Clear wakeup permit.

close back to summary

close	back to summary
public void close() Implements java.lang.AutoCloseable.close. Closes this flock. This method first shuts down the flock to prevent new threads from starting. It then waits for the threads in the flock to finish executing their tasks. In other words, this method blocks until all threads in the flock finish. This method may only be invoked by the flock owner. If interrupted then this method continues to wait until all threads finish, before completing with the interrupted status set. A ThreadFlock is intended to be used in a structured manner. If this method is called to close a flock before nested flocks are closed then it closes the nested flocks (in the reverse order that they were created in), closes this flock, and then throws `StructureViolationException`. Similarly, if this method is called to close a thread flock while executing with scoped value bindings, and the thread flock was created before the scoped values were bound, then `StructureViolationException` is thrown after closing the thread flock. Exceptions WrongThreadException: if invoked by a thread that is not the owner StructureViolationException: if a structure violation was detected

public void close()

Implements java.lang.AutoCloseable.close.

Closes this flock. This method first shuts down the flock to prevent new threads from starting. It then waits for the threads in the flock to finish executing their tasks. In other words, this method blocks until all threads in the flock finish.

This method may only be invoked by the flock owner.

If interrupted then this method continues to wait until all threads finish, before completing with the interrupted status set.

A ThreadFlock is intended to be used in a structured manner. If this method is called to close a flock before nested flocks are closed then it closes the nested flocks (in the reverse order that they were created in), closes this flock, and then throws StructureViolationException. Similarly, if this method is called to close a thread flock while executing with scoped value bindings, and the thread flock was created before the scoped values were bound, then StructureViolationException is thrown after closing the thread flock.

Exceptions

WrongThreadException:: if invoked by a thread that is not the owner
StructureViolationException:: if a structure violation was detected

containsThread back to summary

containsThread	back to summary
public boolean containsThread(Thread thread) Tests if this flock contains the given thread. This method returns `true` if the thread was started in this flock and has not finished. If the thread is not in this flock then it tests if the thread is in flocks owned by threads in this flock, essentially equivalent to invoking `containsThread` method on all flocks owned by the threads in this flock. Parameters thread:Thread the thread Returns:boolean true if this flock contains the thread

public boolean containsThread(Thread thread)

Tests if this flock contains the given thread. This method returns true if the thread was started in this flock and has not finished. If the thread is not in this flock then it tests if the thread is in flocks owned by threads in this flock, essentially equivalent to invoking containsThread method on all flocks owned by the threads in this flock.

Parameters

thread:Thread: the thread

Returns:boolean

true if this flock contains the thread

decrementThreadCount	back to summary
private void decrementThreadCount() Decrement the thread count. Unpark the owner if the count goes to zero.

ensureOwner	back to summary
private void ensureOwner() Throws WrongThreadException if the current thread is not the owner.

ensureOwnerOrContainsThread	back to summary
private void ensureOwnerOrContainsThread() Throws WrongThreadException if the current thread is not the owner or a thread contained in the flock.

getAndSetPermit	back to summary
private boolean getAndSetPermit(boolean newValue) Sets the wakeup permit to the given value, returning the previous value.

incrementThreadCount	back to summary
private void incrementThreadCount()

isClosed	back to summary
public boolean isClosed() Returns true if the flock has been closed. Returns:boolean true if the flock has been closed

isClosed

back to summary

public boolean isClosed()

Returns true if the flock has been closed.

Returns:boolean: true if the flock has been closed

isShutdown	back to summary
public boolean isShutdown() Returns true if the flock has been shut down. Returns:boolean true if the flock has been shut down

isShutdown

back to summary

public boolean isShutdown()

Returns true if the flock has been shut down.

Returns:boolean: true if the flock has been shut down

name back to summary

name	back to summary
public String name() Returns the name of this flock or `null` if unnamed. Returns:String the name of this flock or `null` if unnamed

public String name()

Returns the name of this flock or null if unnamed.

Returns:String: the name of this flock or null if unnamed

onExit	back to summary
private void onExit(Thread thread) Invoked on the terminating thread or the parent thread when starting `thread` failed. This method is only called if onStart succeeded.

onStart	back to summary
private void onStart(Thread thread) Invoked on the parent thread when starting `thread`.

open	back to summary
public static ThreadFlock open(String name) Opens a new thread flock. The flock is owned by the current thread. It can be named to aid debugging. This method captures the current thread's scoped value bindings for inheritance by threads created in the flock. For the purposes of containment, monitoring, and debugging, the parent of the new flock is determined as follows: If the current thread is the owner of open flocks then the most recently created, and open, flock is the parent of the new flock. In other words, the enclosing flock is the parent. If the current thread is not the owner of any open flocks then the parent of the new flock is the current thread's flock. If the current thread was not started in a flock then the new flock does not have a parent. Parameters name:String the name of the flock, can be null Returns:ThreadFlock a new thread flock

open

back to summary

public static ThreadFlock open(String name)

Opens a new thread flock. The flock is owned by the current thread. It can be named to aid debugging.

This method captures the current thread's scoped value bindings for inheritance by threads created in the flock.

For the purposes of containment, monitoring, and debugging, the parent of the new flock is determined as follows:

If the current thread is the owner of open flocks then the most recently created, and open, flock is the parent of the new flock. In other words, the enclosing flock is the parent.
If the current thread is not the owner of any open flocks then the parent of the new flock is the current thread's flock. If the current thread was not started in a flock then the new flock does not have a parent.

Parameters

name:String: the name of the flock, can be null

Returns:ThreadFlock

a new thread flock

owner	back to summary
public Thread owner() Returns the owner of this flock. Returns:Thread the owner of this flock

owner

back to summary

public Thread owner()

Returns the owner of this flock.

Returns:Thread: the owner of this flock

scopedValueBindings	back to summary
private ScopedValueContainer.BindingsSnapshot scopedValueBindings()

shutdown	back to summary
public void shutdown() Shutdown this flock so that no new threads can be started, existing threads in the flock will continue to run. This method is a no-op if the flock is already shutdown or closed.

start	back to summary
public Thread start(Thread thread) Starts the given unstarted thread in this flock. The thread is started with the scoped value bindings that were captured when opening the flock. The bindings must match the current thread's bindings. This method may only be invoked by the flock owner or threads contained in the flock. Parameters thread:Thread the unstarted thread Returns:Thread the thread, started Exceptions IllegalStateException: if this flock is shutdown or closed IllegalThreadStateException: if the given thread was already started WrongThreadException: if the current thread is not the owner or a thread contained in the flock StructureViolationException: if the current scoped value bindings are not the same as when the flock was created

start

back to summary

public Thread start(Thread thread)

Starts the given unstarted thread in this flock.

The thread is started with the scoped value bindings that were captured when opening the flock. The bindings must match the current thread's bindings.

This method may only be invoked by the flock owner or threads contained in the flock.

Parameters

thread:Thread: the unstarted thread

Returns:Thread

the thread, started

Exceptions

IllegalStateException:: if this flock is shutdown or closed
IllegalThreadStateException:: if the given thread was already started
WrongThreadException:: if the current thread is not the owner or a thread contained in the flock
StructureViolationException:: if the current scoped value bindings are not the same as when the flock was created

threadCount	back to summary
private long threadCount()

threads	back to summary
public Stream<Thread> threads() Returns a stream of the threads in this flock. The elements of the stream are threads that were started in this flock but have not terminated. The stream will reflect the set of threads in the flock at some point at or since the creation of the stream. It may or may not reflect changes to the set of threads subsequent to creation of the stream. Returns:Stream<Thread> a stream of the threads in this flock

threads

back to summary

public Stream<Thread> threads()

Returns a stream of the threads in this flock. The elements of the stream are threads that were started in this flock but have not terminated. The stream will reflect the set of threads in the flock at some point at or since the creation of the stream. It may or may not reflect changes to the set of threads subsequent to creation of the stream.

Returns:Stream<Thread>: a stream of the threads in this flock

toString back to summary

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Doc from java.lang.Object.toString. Returns a string representation of the object. Satisfying this method's contract implies a non-`null` result must be returned. Annotations @Override

public String toString()

Overrides java.lang.Object.toString.

Doc from java.lang.Object.toString.

Returns a string representation of the object. Satisfying this method's contract implies a non-null result must be returned.

Annotations

@Override

wakeup back to summary

wakeup	back to summary
public void wakeup() Causes the call to `awaitAll()` or `awaitAll(Duration)` by the owner to return immediately. If the owner is blocked in `awaitAll` then it will return immediately. If the owner is not blocked in `awaitAll` then its next call to wait will return immediately. The method does nothing when the flock is closed.

public void wakeup()

Causes the call to awaitAll() or awaitAll(Duration) by the owner to return immediately.

If the owner is blocked in awaitAll then it will return immediately. If the owner is not blocked in awaitAll then its next call to wait will return immediately. The method does nothing when the flock is closed.

jdk.internal.misc back to summary

private Class ThreadFlock.ThreadContainerImpl

Class Inheritance

extends ThreadContainer

java.lang.Object
jdk.internal.vm.StackableScope
jdk.internal.vm.ThreadContainer
jdk.internal.misc.ThreadFlock.ThreadContainerImpl

A ThreadContainer backed by a ThreadFlock.

Field Summary

Modifier and Type	Field and Description
private boolean	closing
private final ThreadFlock	flock
private volatile Object	key

Constructor Summary

Access	Constructor and Description
pack-priv	ThreadContainerImpl(ThreadFlock flock)

Method Summary

Modifier and Type	Method and Description
pack-priv void	close() Invoked by ThreadFlock.close when closing the flock.
public String	name() Overrides jdk.internal.vm.ThreadContainer.name. Return the name of this container, may be null.
public void	onExit(Thread thread) Overrides jdk.internal.vm.ThreadContainer.onExit. Invoked by `remove` to remove a thread from this container when it terminates (or failed to start).
public void	onStart(Thread thread) Overrides jdk.internal.vm.ThreadContainer.onStart. Invoked by `add` to add a thread to this container before it starts.
public ThreadFlock.ThreadContainerImpl	push() Overrides jdk.internal.vm.StackableScope.push. Pushes this scope onto the current thread's scope stack.
public ScopedValueContainer.BindingsSnapshot	scopedValueBindings() Overrides jdk.internal.vm.ThreadContainer.scopedValueBindings. The scoped values captured when the thread container was created.
public long	threadCount() Overrides jdk.internal.vm.ThreadContainer.threadCount. Return a count of the number of threads in this container.
public Stream<Thread>	threads() Implements abstract jdk.internal.vm.ThreadContainer.threads. Returns a stream of the live threads in this container.
protected boolean	tryClose() Overrides jdk.internal.vm.StackableScope.tryClose. Invoked when an enclosing scope is closing.

Inherited from jdk.internal.vm.ThreadContainer:: add children parent remove toString

Field Detail

closing	back to summary
private boolean closing

flock	back to summary
private final ThreadFlock flock

key	back to summary
private volatile Object key

Constructor Detail

ThreadContainerImpl	back to summary
pack-priv ThreadContainerImpl(ThreadFlock flock)

Method Detail

close	back to summary
pack-priv void close() Invoked by ThreadFlock.close when closing the flock. This method pops the container from the current thread's scope stack.

name	back to summary
public String name() Overrides jdk.internal.vm.ThreadContainer.name. Doc from jdk.internal.vm.ThreadContainer.name. Return the name of this container, may be null. Annotations @Override

name

back to summary

public String name()

Overrides jdk.internal.vm.ThreadContainer.name.

Doc from jdk.internal.vm.ThreadContainer.name.

Return the name of this container, may be null.

Annotations

@Override

onExit back to summary

onExit	back to summary
public void onExit(Thread thread) Overrides jdk.internal.vm.ThreadContainer.onExit. Doc from jdk.internal.vm.ThreadContainer.onExit. Invoked by `remove` to remove a thread from this container when it terminates (or failed to start). Annotations @Override

public void onExit(Thread thread)

Overrides jdk.internal.vm.ThreadContainer.onExit.

Doc from jdk.internal.vm.ThreadContainer.onExit.

Invoked by remove to remove a thread from this container when it terminates (or failed to start).

Annotations

@Override

onStart back to summary

public void onStart(Thread thread)

Overrides jdk.internal.vm.ThreadContainer.onStart.

Doc from jdk.internal.vm.ThreadContainer.onStart.

Invoked by add to add a thread to this container before it starts.

Annotations

@Override

push

back to summary

public ThreadFlock.ThreadContainerImpl push()

Overrides jdk.internal.vm.StackableScope.push.

Doc from jdk.internal.vm.StackableScope.push.

Pushes this scope onto the current thread's scope stack.

Annotations

@Override

scopedValueBindings

back to summary

public ScopedValueContainer.BindingsSnapshot scopedValueBindings()

Overrides jdk.internal.vm.ThreadContainer.scopedValueBindings.

Doc from jdk.internal.vm.ThreadContainer.scopedValueBindings.

The scoped values captured when the thread container was created.

Annotations

@Override

threadCount

back to summary

public long threadCount()

Overrides jdk.internal.vm.ThreadContainer.threadCount.

Doc from jdk.internal.vm.ThreadContainer.threadCount.

Return a count of the number of threads in this container.

Annotations

@Override

threads

back to summary

public Stream<Thread> threads()

Implements abstract jdk.internal.vm.ThreadContainer.threads.

Doc from jdk.internal.vm.ThreadContainer.threads.

Returns a stream of the live threads in this container.

Annotations

@Override

tryClose

back to summary

protected boolean tryClose()

Overrides jdk.internal.vm.StackableScope.tryClose.

Invoked when an enclosing scope is closing. Invokes ThreadFlock.close to close the flock. This method does not pop the container from the current thread's scope stack.

Annotations

@Override

public Class ThreadFlock

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private Class ThreadFlock.ThreadContainerImpl

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail