[asterisk-scf-commits] asterisk-scf/integration/slice.git branch "workqueue" updated.
Commits to the Asterisk SCF project code repositories
asterisk-scf-commits at lists.digium.com
Thu Apr 7 22:15:20 CDT 2011
branch "workqueue" has been updated
via 86ae6dcd9240f59c511281c63a4ee10f4d897473 (commit)
from b2f2ff479f36b49511c0ed021b488d7ca2996774 (commit)
Summary of changes:
AsteriskSCF/System/ThreadPool/ThreadPoolIf.ice | 65 ++++++++
AsteriskSCF/System/WorkQueue/WorkQueueIf.ice | 186 +++++++++++++++++++++++-
2 files changed, 243 insertions(+), 8 deletions(-)
- Log -----------------------------------------------------------------
commit 86ae6dcd9240f59c511281c63a4ee10f4d897473
Author: Mark Michelson <mmichelson at digium.com>
Date: Thu Apr 7 22:14:05 2011 -0500
Add some documentation to thread pool and work queue interfaces.
diff --git a/AsteriskSCF/System/ThreadPool/ThreadPoolIf.ice b/AsteriskSCF/System/ThreadPool/ThreadPoolIf.ice
index ea40393..c3e9c9f 100644
--- a/AsteriskSCF/System/ThreadPool/ThreadPoolIf.ice
+++ b/AsteriskSCF/System/ThreadPool/ThreadPoolIf.ice
@@ -30,21 +30,86 @@ module ThreadPool
module V1
{
+ /**
+ * A thread pool
+ *
+ * The Pool maintains a Queue of Work to execute. Users of the
+ * Pool feed it Work by adding to this Queue directly.
+ */
local interface Pool
{
+ /**
+ * Set the number of threads in the Pool
+ *
+ * This method may be used to either add or
+ * remove threads from the pool.
+ *
+ * @param size The number of threads for the pool to be
+ * resized to.
+ */
void setSize(int size);
+
+ /**
+ * Get a handle to the Pool's Queue
+ *
+ * @return The Pool's Queue
+ */
AsteriskSCF::System::WorkQueue::V1::Queue getQueue();
};
+ /**
+ * Listener for events from a Pool
+ *
+ * All methods include as a parameter a handle to the Pool
+ * in case the listener wishes to alter the Pool as a result
+ * of the reported event.
+ */
local interface PoolListener
{
+ /**
+ * Indicates that the state of one or more of the Pool's threads has changed
+ *
+ * @param tpool A handle to the Pool
+ * @param activeThreads The number of active threads. Active threads are those
+ * that are currently executing work.
+ * @param idleThreads The number of idle threads. Idle threads are those that
+ * are currently waiting for work to be added.
+ * @param zombieThreads The number of zombie threads. Zombie threads are those
+ * that are still executing work but are marked for destruction as soon as they
+ * finish.
+ */
void stateChanged(Pool tpool, int activeThreads, int idleThreads, int zombieThreads);
+
+ /**
+ * Indicates that the Pool's queue has had work added to it.
+ *
+ * @param tpool A handle to the Pool
+ * @param newWorkCount The number of new items added to the Queue
+ * @param wasEmpty True if the Queue was empty prior to the addition of
+ * new Work. False otherwise.
+ */
void queueWorkAdded(Pool tpool, int newWorkCount, bool wasEmpty);
+
+ /**
+ * Indicates that the Pool's queue is empty
+ *
+ * @param tpool A handle to the Pool
+ */
void queueEmptied(Pool tpool);
};
+ /**
+ * Factory class for creating Pools
+ */
local interface PoolFactory
{
+ /**
+ * Creates a new Pool
+ *
+ * @param listener The PoolListener for the Pool to report events to
+ * @param wqueue The Queue for the ThreadPool to use internally
+ * @return A handle to the newly created Pool
+ */
Pool createPool(PoolListener listener, AsteriskSCF::System::WorkQueue::V1::Queue wqueue);
};
diff --git a/AsteriskSCF/System/WorkQueue/WorkQueueIf.ice b/AsteriskSCF/System/WorkQueue/WorkQueueIf.ice
index a14e043..21df756 100644
--- a/AsteriskSCF/System/WorkQueue/WorkQueueIf.ice
+++ b/AsteriskSCF/System/WorkQueue/WorkQueueIf.ice
@@ -28,71 +28,241 @@ module WorkQueue
module V1
{
+ /**
+ * Receiver of event notices from a Queue or SuspendableQueue
+ *
+ * It is safe to call any Queue or SuspendableQueue operations
+ * from within these methods.
+ */
local interface QueueListener
{
+ /**
+ * Indicates work has been added to the Queue or SuspendableQueue
+ *
+ * @param wasEmpty True if the queue was empty prior
+ * to the addition of the work. False otherwise.
+ */
void workAdded(bool wasEmpty);
+
+ /**
+ * Indicates that suspended work may be resumed
+ *
+ * This method is only ever called by SuspendableQueues
+ */
void workResumable();
+
+ /**
+ * Indicates that the Queue or SuspendableQueue is now empty
+ */
void emptied();
};
+ /**
+ * An item of Work
+ *
+ * Objects derived from this interface may only be
+ * used with Queues, not SuspendableQueues.
+ */
local interface Work
{
+ /**
+ * Execute a task
+ */
void execute();
};
local sequence<Work> WorkSeq;
+ /**
+ * Exception thrown when attempting to cancel a work item that is
+ * not in a Queue or SuspendableQueue
+ */
local exception WorkNotFound
{
};
+ /**
+ * A standard work queue
+ *
+ * Queues maintain a thread-safe FIFO of Work
+ */
local interface Queue
{
+ /**
+ * Enqueue a single item of Work
+ *
+ * @param item The item of Work to enqueue
+ */
void enqueueWork(Work item);
+
+ /**
+ * Enqueue multiple items of Work atomically
+ *
+ * The items will be added in the same order they
+ * appear in the input sequence.
+ *
+ * @param items The sequence of Work to add to the Queue.
+ */
void enqueueWorkSeq(WorkSeq items);
+
+ /**
+ * Cancel a previously queued work item.
+ *
+ * Searches the queue for the specified work item. If found,
+ * the item is removed, otherwise WorkNotFound is thrown. Note
+ * that if multiple copies of a Work item are in the queue, only
+ * the frontmost one will be removed as a result of this method
+ * call.
+ *
+ * @param item The item to be canceled
+ */
void cancelWork(Work item) throws WorkNotFound;
- /* return value indicates whether queue contains more work
- that can be executed immediately
- */
+ /**
+ * Pop the front item from the queue and call its execute() method
+ *
+ * @retval true The queue contains more Work to be executed
+ * @retval false The queue contains no more Work objects
+ */
bool executeWork();
- /* this is a snapshot and should only be used as a hint */
+ /**
+ * Obtain a snapshot of the number of items in the Queue.
+ *
+ * Given that multiple threads may be adding and removing
+ * items from the queue, this should be taken as a hint of
+ * how many items there are rather than as gospel.
+ *
+ * @return The number of Work objects in the Queue
+ */
int getSize();
+ /**
+ * Set a new QueueListener
+ *
+ * If the Queue currently has a listener, then the new
+ * one will replace its old listener.
+ *
+ * @param listener The new QueueListener to set
+ */
void setListener(QueueListener listener);
};
+ /**
+ * The set of potential results from executing SuspendableWork
+ */
enum SuspendableWorkResult
{
+ /**
+ * Work has finished.
+ */
Complete,
+ /**
+ * Work could not be completed immediately
+ */
Suspended
};
+ /**
+ * Listens for updates from SuspendableWork objects
+ */
local interface SuspendableWorkListener
{
+ /**
+ * Indicates that suspended SuspendableWork may be resumed
+ */
void workResumable();
};
+ /**
+ * Work items to be used in a SuspendableQueue
+ */
local interface SuspendableWork
{
+ /**
+ * Executes a piece of SuspendableWork
+ *
+ * @param listener A SuspendableWorkListener to alert when the
+ * SuspendableWork may be resumed.
+ *
+ * @retval Complete The work has completed
+ * @retval Suspended The work cannot be completed at the moment
+ * The listener will be alerted when the SuspendableWork may be resumed.
+ */
SuspendableWorkResult execute(SuspendableWorkListener listener);
};
local sequence<SuspendableWork> SuspendableWorkSeq;
+ /**
+ * A queue of SuspendableWork
+ *
+ * This is much like the Queue but allows for work to
+ * be suspended. This is useful for cases where an item
+ * of work makes an asynchronous RPC and does not wish to
+ * block the thread that is executing work.
+ */
local interface SuspendableQueue
{
+ /**
+ * Enqueue a single item of SuspendableWork
+ *
+ * @param item The item of work to enqueue
+ */
void enqueueWork(SuspendableWork item);
+
+ /**
+ * Enqueue multiple items of SuspendableWork atomically
+ *
+ * The items will be added in the same order they
+ * appear in the input sequence.
+ *
+ * @param items The sequence of SuspendableWork to enqueue
+ */
void enqueueWorkSeq(SuspendableWorkSeq items);
+
+ /**
+ * Cancel a previously queued SuspendableWork item.
+ *
+ * Searches the queue for the specified work item. If found,
+ * the item is removed, otherwise WorkNotFound is thrown. Note
+ * that if multiple copies of a SuspendableWork item are in the
+ * queue, only the frontmost one will be removed as a result of
+ * this method call.
+ *
+ * @param item The item to be canceled
+ */
void cancelWork(SuspendableWork item) throws WorkNotFound;
- /* return value indicates whether queue contains more work
- that can be executed immediately
- */
+ /**
+ * Pop the front item from the queue and call its execute() method
+ *
+ * @retval true The queue contains more SuspendableWork that may
+ * be immediately executed
+ * @retval false The queue either contains no more SuspendableWork
+ * items OR the item executed returned a Suspended result.
+ */
bool executeWork();
- /* this is a snapshot and should only be used as a hint */
+
+ /**
+ * Obtain a snapshot of the number of items in the SuspendableQueue.
+ *
+ * Given that multiple threads may be adding and removing
+ * items from the queue, this should be taken as a hint of
+ * how many items there are rather than as gospel.
+ *
+ * @return The number of SuspendableWork objects in the
+ * SuspendableQueue
+ */
int getSize();
+ /**
+ * Set a new QueueListener
+ *
+ * If the SuspendableQueue currently has a listener, then the new
+ * one will replace its old listener.
+ *
+ * @param listener The new QueueListener to set
+ */
void setListener(QueueListener listener);
};
-----------------------------------------------------------------------
--
asterisk-scf/integration/slice.git
More information about the asterisk-scf-commits
mailing list