agi.foundation.infrastructure.threading

(agi.foundation.core-2024r3.jar)

Class MessageQueue

java.lang.Object

agi.foundation.infrastructure.threading.MessageQueue

All Implemented Interfaces:

IDisposable, AutoCloseable

public class MessageQueue
extends Object
implements IDisposable

A message queue used for passing messages between threads

Constructor Summary

Constructors

Constructor and Description
MessageQueue() Initializes a new instance.

Method Summary

Modifier and Type	Method and Description
void	addMessageQueueStarted(EventHandler<EventArgs> value) Event that indicates MessageQueue has started to receive messages.
void	addMessageQueueStopped(EventHandler<EventArgs> value) Event that indicates MessageQueue has been stopped by a call to MessageQueue.terminate().
void	addMessageReceived(EventHandler<MessageEventArgs> value) Event that indicates a generic message object was received.
void	dispose() Releases any resources associated with this instance.
protected void	dispose(boolean disposing) Releases any resources associated with this instance.
int	getMaximumQueueLength() Gets the maximum number of items that is allowed in the queue.
void	post(Object message) Adds a generic message to the message queue that is asynchronously sent to any functions that subscribe to MessageReceived (add / remove).
void	post(SendOrPostCallback callbackMethod, Object state) Adds a delegate to the message queue and immediately returns.
void	removeMessageQueueStarted(EventHandler<EventArgs> value) Event that indicates MessageQueue has started to receive messages.
void	removeMessageQueueStopped(EventHandler<EventArgs> value) Event that indicates MessageQueue has been stopped by a call to MessageQueue.terminate().
void	removeMessageReceived(EventHandler<MessageEventArgs> value) Event that indicates a generic message object was received.
void	send(Object message) Adds a generic message to the message queue that is synchronously sent to any functions that subscribe to MessageReceived (add / remove).
void	send(SendOrPostCallback callbackMethod, Object state) Adds a delegate to the message queue and waits until all currently queued messages and the given delegate are executed before returning.
void	setMaximumQueueLength(int value) Sets the maximum number of items that is allowed in the queue.
void	start() Runs the message queue in the current thread and does not return until MessageQueue.terminate() is called.
void	startInAnotherThread() Runs the message queue in a separate thread and immediately returns.
void	startInNewThread() Runs the message queue in a newly spawned worker thread and immediately returns.
void	startInNewThread(String name) Runs the message queue in a newly spawned worker thread and immediately returns.
void	startInThreadPoolThread() Runs the message queue in a thread pool thread and immediately returns.
void	terminate() Terminates the message queue.
void	terminateAndWait() Terminates the message queue and waits for termination to complete.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface agi.foundation.compatibility.IDisposable

close

Constructor Detail

MessageQueue

public MessageQueue()

Initializes a new instance.

Method Detail

dispose

public final void dispose()

Releases any resources associated with this instance.

Disposing of a MessageQueue signals the queue to stop pressing messages. If the message queue was started with MessageQueue.start(), the MessageQueue.start() method will return. If the message queue was started with MessageQueue.startInAnotherThread(), the other thread will end.

Specified by:

dispose in interface IDisposable

dispose

protected void dispose(boolean disposing)

Releases any resources associated with this instance.

Parameters:

disposing - true to release both managed and unmanaged resources; false to release only unmanaged resources.

addMessageReceived

public final void addMessageReceived(EventHandler<MessageEventArgs> value)

Event that indicates a generic message object was received. If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

removeMessageReceived

public final void removeMessageReceived(EventHandler<MessageEventArgs> value)

Event that indicates a generic message object was received. If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

addMessageQueueStarted

public final void addMessageQueueStarted(EventHandler<EventArgs> value)

Event that indicates MessageQueue has started to receive messages. If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

removeMessageQueueStarted

public final void removeMessageQueueStarted(EventHandler<EventArgs> value)

Event that indicates MessageQueue has started to receive messages. If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

addMessageQueueStopped

public final void addMessageQueueStopped(EventHandler<EventArgs> value)

Event that indicates MessageQueue has been stopped by a call to MessageQueue.terminate(). If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

removeMessageQueueStopped

public final void removeMessageQueueStopped(EventHandler<EventArgs> value)

Event that indicates MessageQueue has been stopped by a call to MessageQueue.terminate(). If MessageQueue was started with a call to MessageQueue.startInAnotherThread(), this event will be raised in that other thread.

getMaximumQueueLength

public final int getMaximumQueueLength()

Gets the maximum number of items that is allowed in the queue. If a thread attempts to add an item to a full queue, it will block until room is available in the queue.

setMaximumQueueLength

public final void setMaximumQueueLength(int value)

Sets the maximum number of items that is allowed in the queue. If a thread attempts to add an item to a full queue, it will block until room is available in the queue.

startInThreadPoolThread

public final void startInThreadPoolThread()

Runs the message queue in a thread pool thread and immediately returns. The worker thread will not be released back to the thread pool until MessageQueue.terminate() is called.

startInNewThread

public final void startInNewThread()

Runs the message queue in a newly spawned worker thread and immediately returns. The worker thread will not be terminated until MessageQueue.terminate() is called.

startInNewThread

public final void startInNewThread(String name)

Runs the message queue in a newly spawned worker thread and immediately returns. The worker thread will not be terminated until MessageQueue.terminate() is called.

Parameters:

name - The name of the thread. Naming a thread can make it easier to identify while debugging.

startInAnotherThread

public final void startInAnotherThread()

Runs the message queue in a separate thread and immediately returns. This method calls MessageQueue.startInThreadPoolThread() or MessageQueue.startInNewThread() depending on the value of ThreadSource (get / set) in the ThreadingPolicy.

start

public final void start()

Runs the message queue in the current thread and does not return until MessageQueue.terminate() is called.

send

public final void send(@Nonnull
                       SendOrPostCallback callbackMethod,
                       Object state)

Adds a delegate to the message queue and waits until all currently queued messages and the given delegate are executed before returning.

Parameters:

callbackMethod - The SendOrPostCallback delegate to call.

state - The object passed to the delegate.

Throws:

IllegalStateException - The queue is not started.

ArgumentNullException - Thrown when callbackMethod is null.

send

public final void send(Object message)

Adds a generic message to the message queue that is synchronously sent to any functions that subscribe to MessageReceived (add / remove).

Parameters:

message - The message to send.

Throws:

IllegalStateException - The queue is not started.

post

public final void post(@Nonnull
                       SendOrPostCallback callbackMethod,
                       Object state)

Adds a delegate to the message queue and immediately returns.

Parameters:

callbackMethod - The SendOrPostCallback delegate to call.

state - The object passed to the delegate.

Throws:

ArgumentNullException - Thrown when callbackMethod is null.

post

public final void post(Object message)

Adds a generic message to the message queue that is asynchronously sent to any functions that subscribe to MessageReceived (add / remove).

Parameters:

message - The message to send.

terminate

public final void terminate()

Terminates the message queue.

Any messages that are already in the queue when this method is called will be processed before the queue is terminated. This method initiates the termination and returns immediately; it does NOT wait for the termination to complete before returning. It is safe to call this method from any thread, including the thread that is processing the message queue. To wait for termination to complete, call MessageQueue.terminateAndWait() instead. If the queue is not running when this method is called, the termination request will still be posted. That means that queue processing, once restarted, will terminate once it reaches this point in the queue.

terminateAndWait

public final void terminateAndWait()

Terminates the message queue and waits for termination to complete.

Any messages that are already in the queue when this method is called will be processed before the queue is terminated. Unlike MessageQueue.terminate(), this method does not return until the message queue is terminated. This method must not be called from the thread that is running the message queue. Doing so will cause a deadlock, because this method cannot return until the message queue terminates, and the queue cannot terminate until this method returns.

Throws:

IllegalStateException - The queue is not started.