SUMMARY: CONSTR | METHOD | DETAIL: CONSTR | METHOD |
Note: this object is derived from an threads::shared arrayref to optimize performance.
Licensed under the Academic Free License version 2.1, as specified in the License.txt file included in this software package, or at OpenSource.org.
Unless otherwise noted, $obj
is the object instance variable.
Exported Symbols | |
---|---|
$tqd_global_lock | global threads::shared variable for locking |
TQD_Q | object field index of threads::shared array used for the queue |
TQD_MAP | object field index of threads::shared hash mapping queue request IDs to requests/responses |
TQD_IDGEN | object field index of threads::shared scalar integer used to generate request IDs |
TQD_LISTENERS | object field index of threads::shared scalar integer count of current listeners |
TQD_REQUIRE_LISTENER | object field index of threads::shared scalar flag indicating if listeners are required before permitting an enqueue operation |
TQD_MAX_PENDING | object field index of threads::shared scalar integer max number of pending requests before an enqueue will block |
TQD_URGENT_COUNT | object field index of threads::shared scalar integer count of current urgent requests |
TQD_MARKS | object field index of threads::shared hash mapping request IDs of marked requests |
Constructor Summary |
---|
new(ListenerRequired => value, MaxPending => value)
Creates a new empty queue, and associated mapping hash |
Method Summary |
---|
available(@ids)
Test if a response is available for a either any request, or for any of a set of requests |
cancel(@ids)
Cancel one or more pending requests |
cancel_all()
Cancel all current requests and responses, using the cancel() algorithm above, plus cancels all simplex requests still in the queue |
dequeue()
Dequeue the next request |
dequeue_nb()
Dequeue the next request |
dequeue_until($timeout)
Dequeue the next request |
dequeue_urgent()
Dequeue the next urgent request |
enqueue(@args)
Enqueue a request to the tail of the queue |
enqueue_and_wait(@args)
Enqueue a request to the tail of the queue, and wait for the response |
enqueue_and_wait_until($timeout, @args)
Enqueue a request to the tail of the queue, and wait up to $timeout seconds for the response |
enqueue_simplex(@args)
Enqueue a simplex request to the tail of the queue |
enqueue_simplex_urgent(@args)
Enqueue a simplex request to the head of the queue |
enqueue_urgent(@args)
Enqueue a request to the head of the queue |
enqueue_urgent_and_wait(@args)
Enqueue a request to the head of the queue, and wait up to $timeout seconds for the response |
enqueue_urgent_and_wait_until($timeout, @args)
Enqueue a request to the head of the queue, and wait up to $timeout seconds for the response |
get_mark($id)
Returns any current mark on a specified request |
ignore()
Deregister as a queue listener |
listen()
Register as a queue listener |
mark($id, $value)
Mark a request with a value |
marked($id, $value)
Test if a request is marked, or if the mark is a specified value |
pending()
Report the number of pending requests |
ready($id)
Test if a response is available for a specific request |
respond($id, @response)
Post a response to a request |
set_max_pending($limit)
Set maximum number of pending requests permitted |
unmark($id)
Remove any marks from a request |
wait($id)
Wait for a response to a request |
wait_all(@IDs_or_container_refs)
Wait for a response to all specified requests |
wait_all_until($timeout, @IDs_or_container_refs)
Wait up to $timeout seconds for a response to all specified requests |
wait_any(@IDs_or_container_refs)
Wait for a response to any specified request |
wait_any_until($timeout, @IDs_or_container_refs)
Wait up to $timeout seconds for a response to any specified request |
wait_for_listener($timeout)
Wait until a listener has registered |
wait_until($id, $timeout)
Wait up to $timeout seconds for a response to a request |
Constructor Details |
---|
new(ListenerRequired => value, MaxPending => value)
ListenerRequired
=> boolean value indicating if registered listener
required before enqueue is permitted.
MaxPending
=> positive integer maximum number of pending requests;
enqueue attempts will block until the pending count
drops below this value. The limit may be applied or modified later
via the set_max_pending() method.
A value of zero indicates no limit.
Method Details |
---|
available(@ids)
@ids
- (optional) list of request IDs of responses for which to test.
cancel(@ids)
If a response to a cancelled request has already been posted to the queue response map (i.e., the request has already been serviced), the response is removed from the map, the Thread::Queue::Queueable object in the response, and the response is discarded.
If a response to a cancelled request has not yet been posted to the queue response map, an empty entry is added to the queue response map. (Note: threads::shared doesn't permit splicing shared arrays yet, so we can't remove the request from the queue).
When a server thread attempts to dequeue[_nb|_until]()
a cancelled
request, the request is discarded and the dequeue operation is retried.
If the cancelled request is already dequeued, the server thread will
detect the cancellation when it attempts to respond to the request,
and will invoke the Thread::Queue::Queueable
objects in the response, and then discards the response.
Note that, as simplex requests do not have an identifier, there is no way to explicitly cancel a specific simplex request.
@ids
- list of request IDs to be cancelled.
cancel_all()
Note: In-progress requests (i.e., request which have been removed from the queue, but do not yet have an entry in the response map) will not be cancelled.
dequeue()
dequeue_nb()
dequeue_until($timeout)
$timeout
- number of seconds to wait for a request
dequeue_urgent()
enqueue(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_and_wait(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_and_wait_until($timeout, @args)
$timeout
- number of seconds to wait for a response
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_simplex(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_simplex_urgent(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_urgent(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_urgent_and_wait(@args)
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
enqueue_urgent_and_wait_until($timeout, @args)
$timeout
- number of seconds to wait for a response
@args
- the request. Request values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
get_mark($id)
$id
- ID of request whose mark is to be returned.
ignore()
listen()
mark($id, $value)
$id
- ID of request to be marked
$value
- (optional) value to be added as a mark; if not specified,
a default value of 1 is used.
marked($id, $value)
$id
- ID of request to test for a mark
$value
- (optional) value to test for
pending()
ready($id)
$id
- the request ID of the response for which to test.
respond($id, @response)
$id
- the ID of the request being responded to.
@response
- the response. Response values must be either scalars,
references to threads::shared variables, or Thread::Queue::Queueable
objects
set_max_pending($limit)
$limit
- positive integer maximum number of pending requests permitted.
A value of zero indicates no limit.
unmark($id)
$id
- ID of request to be unmarked.
wait($id)
dequeue_response()
alias.
$id
- the request ID of the response for which to wait.
wait_all(@IDs_or_container_refs)
As an instance method, a list of request IDs is provided, and the method waits for a response event on all of the specified requests.
As a class method, the caller provides a list of either Thread::Queue::TQDContainer objects, or arrayrefs with a Thread::Queue::TQDContainer object, and zero or more request IDs. For Thread::Queue::TQDContainer object arguments, and arrayref arguments with no identifiers, waits for responses to all current requests on the queue. For arrayref arguments with IDS, waits for a response to all of the specified IDs.
@IDs_or_container_refs
- as instance method, a list of request IDs to wait for;
as class method, a list of either of Thread::Queue::TQDContainer objects,
or arrayrefs containing a Thread::Queue::TQDContainer object, followed by
zero or more request IDs for the queue object.
wait_all_until($timeout, @IDs_or_container_refs)
As an instance method, a list of request IDs is provided, and the method waits for a response event on all of the specified requests.
As a class method, the caller provides a list of either Thread::Queue::TQDContainer objects, or arrayrefs with a Thread::Queue::TQDContainer object, and zero or more request IDs. For Thread::Queue::TQDContainer object arguments, and arrayref arguments with no identifiers, waits for responses to all current requests on the queue. For arrayref arguments with IDS, waits for a response to all of the specified IDs.
$timeout
- number of seconds to wait for all response
@IDs_or_container_refs
- as instance method, a list of request IDs to wait for;
as class method, a list of either of Thread::Queue::TQDContainer objects,
or arrayrefs containing a Thread::Queue::TQDContainer object, followed by
zero or more request IDs for the queue object.
wait_any(@IDs_or_container_refs)
As an instance method, a list of request IDs is provided, and the method waits for a response event on any of the specified requests.
As a class method, the caller provides a list of either Thread::Queue::TQDContainer objects (TQD is itself a TQDContainer), or arrayrefs with a Thread::Queue::TQDContainer object, and zero or more request IDs. For Thread::Queue::TQDContainer object arguments, and arrayref arguments with no identifiers, waits for any enqueue event on the contained queue. For arrayref arguments with IDS, waits for a response event for any of the specified IDs.
@IDs_or_container_refs
- as instance method, a list of request IDs to wait for;
as class method, a list of either of Thread::Queue::TQDContainer objects,
or arrayrefs containing a Thread::Queue::TQDContainer object, followed by
zero or more request IDs for the queue object.
wait_any_until($timeout, @IDs_or_container_refs)
As an instance method, a list of request IDs is provided, and the method waits for a response event on any of the specified requests.
As a class method, the caller provides a list of either Thread::Queue::TQDContainer objects, or arrayrefs with a Thread::Queue::TQDContainer object, and zero or more request IDs. For Thread::Queue::TQDContainer object arguments, and arrayref arguments with no identifiers, waits for any enqueue event on the queue. For arrayref arguments with IDS, waits for a response event for any of the specified IDs.
$timeout
- number of seconds to wait for a response event
@IDs_or_container_refs
- as instance method, a list of request IDs to wait for;
as class method, a list of either of Thread::Queue::TQDContainer objects,
or arrayrefs containing a Thread::Queue::TQDContainer object, followed by
zero or more request IDs for the queue object.
wait_for_listener($timeout)
$timeout
- (optional) number of seconds to wait for a listener.
wait_until($id, $timeout)
$id
- the request ID of the response for which to wait.
$timeout
- number of seconds to wait