NAME
HPCI::TimeoutQueue;SYNOPSIS
Manage a collection of requests for timeout notifications.
DESCRIPTION
This is used internally to HPCI - no user-serviceable parts to be found here.
A TimeoutQueue keeps a list of outstanding timeout entries. Each entry consists of a time when it will trigger (passed in as seconds until trigger, stored internally as epoch time of the trigger moment), an object to be informed, along with the name of the method to call to inform the object, and any additional arguments required.
They are kept in a list, sorted in trigger order.
When entries are deleted before being triggered, they are deleted only if they are at an end of the list. They are not removed if they are in the middle of the list; instead the object field is set to undef.
When a new object is being inserted, it will replace a "deleted" entry (undef object) if there is one in an acceptable spot.
METHODS
new
No arguments, initials a new TimeoutQueue object.
delete_timeouts( $object [, method_name [, arg ...] ] )
Deletes all timeouts which match the specified object (and method and arg values if provided).
It may sometimes make sense to provide arg values that the method will ignore, if there is a need to be able to selectively disable specific timeouts while leaving others intact.
expire_timeouts
Trigger all timeouts that have expired. Returns a list of them in array context, a count of the number triggered in scalar context, or nothing.
time_to_next_timeout
Return the time until the next timeout will trigger. A zero or negative means that there is one or more not yet triggered timeout that is already (over)due.
Returns undef if the queue is empty.
add_timeout( seconds_until_trigger, object, method[, args ...] )
Add a timeout trigger entry to the queue.
The time until the trigger is given in seconds, but is converted to seconds from epoch by adding the current time to it.
If the trigger time is reached without the entry being deleted, the specified object will be notified using the specified method (and any additional specified arguments).
This method is complicated somewhat because it tries to find a previously deleted entry that can be replaced.
_clean_front
_clean_back
The state of the TimeoutQueue, execpt in the middle of internal operations, guarantees that the first and last entries in the list (if there are any entries) are not deleted elements.
_clean_front and _clean_back are internal methods used to re-establish this assertion whenever any action is taken that might have disrupted it.
AUTHOR
John Macdonald - Boutros Lab
ACKNOWLEDGEMENTS
Paul Boutros, Phd, PI - Boutros Lab
The Ontario Institute for Cancer Research