shadow:standard@Thread:Current
shadow:standard@CanIndex<int,shadow:standard@Thread>
locked class Thread
Class Thread
provides ways to manipulate threads. All threads are required to terminate for the main process to terminate as well. If the main method returns and there are still running threads ... what will happen?
Claude Abounegm
Barry Wittman
Modifiers | Return Types | Method and Description |
---|---|---|
protected |
() |
create(nullable String name, CanRun runner) Creates a new |
protected |
() |
create(CanRun runner) Creates a new |
Modifiers | Return Types | Method and Description |
---|---|---|
public |
() |
destroy() |
Modifiers | Return Types | Method and Description |
---|---|---|
protected locked |
() |
addChild(Thread thread) |
public readonly locked |
(Thread) |
childAt(int index) Gets the n-th child that this thread spawned. |
public readonly locked |
(CanIterate<Thread>) |
children() Gets the children of this thread. |
public readonly locked |
(CanIterate<Thread>) |
children(boolean recurse) Gets the children of this thread. |
public readonly |
(Thread) |
copy(AddressMap addresses) |
public readonly locked |
(Thread) |
index(int index) Gets the n-th child that this thread spawned. |
public locked |
() |
interrupt() Requests this thread to be interrupted. |
public locked |
() |
join()
|
public locked |
(boolean) |
join(int millisecondsTimeout)
|
public locked |
(boolean) |
join(TimeSpan timeout)
|
protected locked |
(Object, Thread) |
receiveFirst(Class expectedType, boolean blocking)
|
protected locked |
(Object) |
receiveFirstFrom(Class expectedType, Thread from, boolean blocking)
|
protected locked |
() |
sendTo(Object data, boolean blocking)
|
public readonly locked |
(String) |
toString() Returns a string with the format: "Thread ({Thread->name}): {Thread->stateString}". |
Modifiers | Return Types | Method and Description |
---|---|---|
public readonly get locked |
(int) |
childrenCount() Gets the number of children the thread currently has. |
public readonly get locked |
(int) |
id() Gets the Shadow-specific thread ID. |
public readonly get locked |
(boolean) |
isAlive() Gets whether this thread is running. |
public readonly get locked |
(String) |
name() Gets the name of the thread set at spawn time. |
public readonly get locked |
(nullable Thread) |
parent() Gets the |
public readonly get locked |
(int) |
state() Gets the state of this thread. |
public readonly get locked |
(String) |
stateString() Gets the string representation of the state of this thread. |
protected create(nullable String name, CanRun runner) => ()
Creates a new Thread
object which takes on a CanRun
instance, containing a run function that is going to be run on a different thread, and takes a String
which is the name of the thread for reference purposes.
name
- The name of the thread.
runner
- The instance that contains a run function.
protected create(CanRun runner) => ()
Creates a new Thread
object which takes on a CanRun
instance, containing a run function that is going to be ran on a different thread.
runner
- The instance that contains a run function.
public destroy() => ()
protected locked addChild(Thread thread) => ()
public readonly locked childAt(int index) => (Thread)
Gets the n-th child that this thread spawned. This is NOT the Shadow-specific id.
index
- the index of the child in the range [0, childrenCount).
the n-th child Thread
.
public readonly locked children() => (CanIterate<Thread>)
Gets the children of this thread. This method only enumerates through the first generation children of this thread. i.e. only the thread that this thread spawned.
CanIterate<Thread>
An iterable class to be used with a foreach loop.
public readonly locked children(boolean recurse) => (CanIterate<Thread>)
Gets the children of this thread. If recurse
is true, this method will also traverse the children of the children recursively, until all children have been visited. Care should be taken using this function, as enumerating can throw an exception if the children have changed.
CanIterate<Thread>
An iterable class to be used with a foreach loop.
public readonly copy(AddressMap addresses) => (Thread)
public readonly locked index(int index) => (Thread)
Gets the n-th child that this thread spawned. This is NOT the Shadow-specific id. This is a shortcut to Thread.childAt(), to allow easy indexing of children using Thread[index].
index
- the index of the child in the range [0, childrenCount).
the n-th child Thread
.
public locked interrupt() => ()
Requests this thread to be interrupted. If the thread is currently in the WAITING
state, the thread is interrupted and the method that caused the thread to be in the WAITING
state raises an InterruptedException
. The methods which are interruptible are join()
, sleep()
, send()
, receive()
, and all their overloads. If the thread is not in the WAITING
state, an interrupt flag is set, and the thread is interrupted as soon as one of the above interruptible methods above are called.
true
if the thread was marked as interrupted or false
if the thread wasn't waiting.
public locked join() => ()
Interruptible
. Suspends the execution of the calling thread until this thread terminates. Joining on a dead thread has no side effects. If the thread is terminated because of an exception, the exception is thrown when this method is called.
InvalidOperationException
- if this thread is the main thread or is the same as the calling thread.
ThreadException
- if the thread terminated due to an exception.
InterruptedException
- if another thread requested to interrupt this thread.
public locked join(int millisecondsTimeout) => (boolean)
Interruptible
. Suspends the execution of the calling thread until this thread terminates or until it times out. Joining on a dead thread has no side effects. If the thread is terminated because of an exception, the exception is thrown when this method is called.
millisecondsTimeout
- the time to wait for in milliseconds.
true
if the join returned because of a timeout; otherwise, false
.
InvalidOperationException
- if this thread is the main thread or is the same as the calling thread.
ThreadException
- if the thread terminated due to an exception.
InterruptedException
- if another thread requested to interrupt this thread.
public locked join(TimeSpan timeout) => (boolean)
Interruptible
. Suspends the execution of the calling thread until this thread terminates or until it times out. Joining on a dead thread has no side effects. If the thread is terminated because of an exception, the exception is thrown when this method is called.
timeout
- the time to wait for.
true
if the join returned because of a timeout; otherwise, false
.
InvalidOperationException
- if this thread is the main thread or is the same as the calling thread.
ThreadException
- if the thread terminated due to an exception.
InterruptedException
- if another thread requested to interrupt this thread.
protected locked receiveFirst(Class expectedType, boolean blocking) => (Object, Thread)
Interruptible
. Receives data with the desired expectedType
. This method will throw an exception and will not retrieve the message if the expected type is not the same as the actual one sent by the thread. A thread can send as many messages as it desires, but the receiving thread should always receive the data in the order it was sent; otherwise, an exception is thrown.
IncompatibleMessageTypeException
- If the item attempted to retrieve does not have the same type as expectedType.
InterruptedException
- If this thread was interrupted while waiting on an empty mailbox.
IllegalArgumentException
- If this thread is the same as the from thread.
protected locked receiveFirstFrom(Class expectedType, Thread from, boolean blocking) => (Object)
Interruptible
. Receives data with the desired expectedType
from the desired thread. This method will throw an exception and will not retrieve the message if the expected type is not the same as the actual one sent by the thread. A thread can send as many messages as it desires, but the receiving thread should always receive the data in the order it was sent, or otherwise an exception is thrown.
IncompatibleMessageTypeException
- If the item attempted to retrieve does not have the same type as expectedType.
InterruptedException
- If this thread was interrupted while waiting on an empty mailbox.
IllegalArgumentException
- If this thread is the same as the from thread.
protected locked sendTo(Object data, boolean blocking) => ()
Interruptible
. Sends the desired data to this thread. This method copies all the data before sending it to this thread. Thus no data is shared between two threads. This is a blocking method, and it will block if the mailbox of this thread is full. The method will immediately unblock when there is space for the item to be deposited in the mailbox. Mailbox is first come first serve, and the threads sending data will unblock in the order they were blocked in.
data
- The data to be cloned and sent to this thread.
InterruptedException
- If this thread was interrupted while waiting on a full mailbox.
InvalidOperationException
- if this thread is dead or is the same as the receiving one.
public readonly locked toString() => (String)
Returns a string with the format: "Thread ({Thread->name}): {Thread->stateString}".
public readonly get locked childrenCount() => (int)
Gets the number of children the thread currently has. This method should be used with caution even though it is thread safe. Since a thread can spawn threads at any time, this count can drastically change between each call.
how many children that thread has
public readonly get locked isAlive() => (boolean)
Gets whether this thread is running.
true
if the thread is alive; otherwise, false
.
public readonly get locked name() => (String)
Gets the name of the thread set at spawn time. If no name is set at spawn time, the name takes the format "Thread#{id}".
public readonly get locked parent() => (nullable Thread)
Gets the Thread
which spawned this thread. The Main thread does not have a parent. Once a thread has ended, its parent is set to null.
public readonly get locked state() => (int)
Gets the state of this thread. It can be one of READY
, RUNNING
, WAITING
, or DEAD
.
public readonly get locked stateString() => (String)
Gets the string representation of the state of this thread.