- All Implemented Interfaces:
QueueStatus
,NamedObjectOps
- Direct Known Subclasses:
AbstractWaitTaskQueue
,DelayTaskQueue
,PriorityTaskQueue
- A Processing-time Interval. When an element taken off a queue for processing, this interval determines the time to wait before processing of that element starts. The element will be scheduled on the simulation's event queue with a delay set to the value of the processing-time interval.
- A Time Event Priority. This determines the priority to use when an element is scheduled. The default is 0.0.
The generic type T is the type of a parameter that defines each entry in the queue (the parameter will typically have multiple fields contained in it). A subclass is responsible for providing methods that return the processing-time interval for a parameter and its time event priority.
Subclasses will typically define a number of methods named "add" to
add entries to a queue. After processing the arguments, these methods
will typically just return the value obtained by calling either doAdd,
doAddCallScript, doAddCallObject, or doAddTaskScript. In addition, the
subclass should implement versions of addCurrentTask that create the
parameter used as the first argument to
addCurrentTask(T)
and
addCurrentTask(T, SimEventCallable)
.
As with the methods whose name starts with 'doAdd', The subclasses' versions
of these methods should simply create a parameter from the method's arguments
and then call the appropriate addCurrentTask method defined in TaskQueue.
A subclass created for use by an application only has to implement
the 'add' methods it needs. if the subclass will be put in a
library, one should implement a full set of methods.
There are two protected methods used to configure the queue:
These methods would normally be called by a constructor. For an anonymous class, the protected methodinit()
can be defined. The default
implementation of init()
does nothing but is called by TaskQueue's
constructor. Overriding it will allow additional initializations. The
init()
method is used by subclasses of ServerQueue
defined in
the org.bzdev.devqsim package to create task queues that can be frozen
(these task queues are part of the server queues' implementations).
A subclass also has to implement a queue. This will typically be done
by using a queue or list from the java.util package. The subclass must
implement the method getSize()
to return the queue
size, the method
offerToQueue
to place entries on the queue, and the method
pollFromQueue()
to take an entry off of the queue.
For some classes (e.g., LifoTaskQueue), which supports preempt mode, it
is sometimes necessary to put a scheduled event back on the queue, adjusting
its interval to account for the time it was on the event queue. When this
is the case, the second argument to offerToQueue will be a non-null
TaskQueueSimEvent
and will contain the currently
scheduled event. For this scheduled event, the methods
getOffQueueTime
and
getEventParameters
may be
useful in computing a new interval and modifying the event parameters
to account for that before the event is placed back on the queue.
Task queue entries can be canceled provided they are on a queue as opposed to being scheduled to run. Threads are treated differently from instances of Callable or Runnable.
When a Callable or a Runnable is added to a task queue, a
SimulationEvent will be returned. If this event is null, that
indicates that the attempt to add the Callable or Runnable to the
queue failed (e.g., if the queue has a capacity limit). If this
event is non-null, the operation succeeded. If the event is
canceled (via the cancel
method),
the returned value will be true if the event could be canceled.
The event can be canceled before is is scheduled and if it has not
been canceled previously. If the event cannot be canceled, false
will be returned.
When an existing task is added to a queue it will call a method such as addCurrentTask (subclasses of TaskQueue have methods with this name but with different signatures), which will block while the task is on the queue. The returned value will be true if the task successfully ran and false if the task was removed from the queue or could not be queued. If a variant of addCurrentTask that takes a SimEventCallable is used, the SimEventCallable's call method will be passed a Simulation event that can be canceled. The call to the event's cancel method will return true if the event was removed from the queue and false if the event was already scheduled or had already been canceled.
To implement a timeout for the Callable or Runnable case, code based on the following can be used:
To implement a timeout for a task thread, code based on the following can be used:final SimulationEvent sev = taskQueue.add(new Callable() { public void call() { // operations when queuing was successful } }, PROCESSING_TIME); if (sev == null) { // case where the queuing request failed } else { simulation.scheduleCall(new Callable() { if (sev.cancel()) { // case where the timeout occurred } }, TIMEOUT); }
if (taskQueue.addCurrentTask(PROCESSING_TIME, new SimEventCallable() { public void call(final SimulationEvent sev) { // store sev if it is necessary to tell if the // timeout occurred, in which case sev.isCanceled() // will return true. simulation.scheduleCall(new Callable() { sev.cancel(); }, TIMEOUT); }})) { // normal code } else { // code to run if there was a timeout or a failure to queue the // task. }
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enum
Policies for handling the case where an event is canceled while a release is in progress. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
TaskQueue
(Simulation sim, String name, boolean intern) Constructor -
Method Summary
Modifier and TypeMethodDescriptionboolean
addCurrentTask
(T param) Add the currently running task thread to a queue.boolean
addCurrentTask
(T param, SimEventCallable callable) Add the currently running task thread to a queue.addCurrentTaskObject
(T param) Add the currently running task thread to a queue and return the simulation event generated.void
addObserver
(QueueObserver observer) Add an observer.boolean
Determine if this named object can be deleted.boolean
Determine if a queue can be frozen.boolean
Determine if a a task queue supports preempt mode.boolean
void
Set the number of queued entries guaranteed that will be processed regardless of whether the queue is frozen to zero, provide release operations are supportedprotected Object
clone()
Creates and returns a copy of this object.final boolean
delete()
Delete an object.final boolean
Determine if an object is being deleted.protected TaskQueueSimEvent<T>
Queue an event given a Runnable, a processing-time interval, and a time event priority.protected TaskQueueSimEvent<T>
doAdd
(SimObjectCallable callable, T parameters, long interval, double tpriority) Queue an event given a Callable bound to a simulation object and a time event priority.protected TaskQueueSimEvent<T>
doAdd
(SimObjectRunnable runnable, T parameters, long interval, double tpriority) Queue an event given a Runnable bound to a simulation object and given a processing-time interval and time event priority.protected TaskQueueSimEvent<T>
Queue an event given a Callable and time event priority.protected TaskQueueSimEvent<T>
doAddCallObject
(Object scriptObject, T parameters, long interval, double tpriority) Queue an event given a script object, a processing interval, and a time event priority.protected TaskQueueSimEvent<T>
doAddCallScript
(String script, T parameters, long interval, double tpriority) Queue an event given a script, a processing-time interval, and a time event priority.protected TaskQueueSimEvent<T>
doAddTaskObject
(Object scriptObject, T parameters, long interval, double tpriority) Queue a script object that will run a task, given a processing-time interval and a time event priority.protected TaskQueueSimEvent<T>
doAddTaskScript
(String script, T parameters, long interval, double tpriority) Queue a task that will run a script given a processing-time interval and a time event priority.protected void
Set the number of queued entries guaranteed that will be processed regardless of whether the queue is frozen to zero.protected void
forceFreeze
(boolean value) Sets whether a queue is frozen or not regardless of the value returned by canFreeze.protected void
forceRelease
(int count) Allow a fixed number of entries to be removed from a queue even if the queue is frozen and even if canRelease() returns false.protected void
forceReleaseUpTo
(int count) Allow a fixed number of entries up to the current queue size to be removed from a queue even if the queue is frozen.protected void
Forcibly set the release policyvoid
freeze
(boolean value) Sets whether a queue is frozen or not.Get the current deletion policy for the queue.protected T
getEventParameters
(TaskQueueSimEvent<T> event) Get TaskQueueSimEvent parameters.protected abstract long
getInterval
(T parameters) Find the interval used to schedule a queue entry based on entry's parameters or a default value.final String
getName()
Get an object's name.protected Simulation
Get the object namer for a named object.protected long
getOffQueueTime
(TaskQueueSimEvent<T> event) Get the simulation time at which a TaskQueueSimEvent was removed from a queue.Get the current release policy.protected abstract int
getSize()
Get the raw size of the queue.protected double
getTPriority
(T parameters) Find the time event priority used to schedule a queue entry based on the entry's parameters or a default value of 0.0.protected void
init()
Method to provide additional initializations.int
Determine how many servers are in use.boolean
isBusy()
Determine if the queue is busy.final boolean
Determine if an object has been deleted.boolean
isFrozen()
Determine if a queue is frozen.boolean
Determine if an object is interned in a object namer's tables.boolean
Determine if a scheduled queue entry is being processed.protected abstract boolean
offerToQueue
(TaskQueueSimEvent<T> event, TaskQueueSimEvent<T> scheduled) Put an event on the queue.protected void
onDelete()
Complete the actions necessary to delete a named object.void
pauseCurrentTask
(long interval) Suspend the currently running task thread.void
pauseCurrentTask
(long interval, SimEventCallable callable) Suspend the currently running task thread while it is still the scheduled event.protected abstract TaskQueueSimEvent<T>
Take an event off the queue.void
preempt
(boolean value) Set preempt mode.void
printConfiguration
(String iPrefix, String prefix, boolean printName, PrintWriter out) In addition, the configuration that is printed includes the following: Print this simulation object's configuration.void
printState
(String iPrefix, String prefix, boolean printName, PrintWriter out) Print this simulation object's state.void
release
(int count) Allow a fixed number of entries to be removed from a queue even if the queue is frozen.void
releaseUpTo
(int count) Allow a fixed number of entries up to the current queue size to be removed from a queue even if the queue is frozen.void
removeObserver
(QueueObserver observer) Remove an observer.protected void
replaceScheduledEvent
(TaskQueueSimEvent<T> replacement) Replace the currently scheduled event.int
Determine the maximum number of tasks or calls that can be handled concurrently (equivalent to the number of servers in a queuing system).protected void
setCanFreeze
(boolean value) Set whether a queue can be frozen.protected void
setCanRelease
(boolean value) void
setDeletePolicy
(QueueDeletePolicy policy) Set the deletion policy.protected void
setEventParameters
(TaskQueueSimEvent<T> event, T parameters) Set an event's parameters.void
Set the release policy.int
size()
Get the size of the queue.protected boolean
tryRemove
(TaskQueueSimEvent<T> event) Try to remove an event from the queue.Methods inherited from class org.bzdev.devqsim.DefaultSimObject
getSimulation
Methods inherited from class org.bzdev.devqsim.SimObject
addSimulationListener, addTraceSet, bindCallable, bindCallable, bindCallable, bindCallable, bindRunnable, bindRunnable, bindRunnable, bindRunnable, callableObject, callableScript, callScriptFunction, callScriptMethod, clearTraceSets, evalScript, getEventListenerList, getScriptObject, getTraceSets, printConfiguration, printConfiguration, printConfiguration, printConfiguration, printConfiguration, printConfiguration, printState, printState, printState, printState, printState, printState, putScriptObject, removeSimulationListener, removeTraceSet, runnableObject, runnableScript, scheduleCall, scheduleCall, scheduleCall, scheduleCall, scheduleCallObject, scheduleScript, scheduleTask, scheduleTask, scheduleTask, scheduleTask, scheduleTaskObject, scheduleTaskScript, startImmediateTask, startImmediateTask, trace, trace, unscheduledTaskThread, unscheduledTaskThread, update, update, usesTraceSet
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.bzdev.obnaming.NamedObjectOps
delete, deletePending, getName, isDeleted, isInterned
Methods inherited from interface org.bzdev.devqsim.QueueStatus
getName, isDeleted, isInterned
-
Constructor Details
-
TaskQueue
Constructor- Parameters:
sim
- the simulationname
- the name of the task queueintern
- true if the object should be interned (so it can be looked up by name).- Throws:
IllegalArgumentException
- typically means a name is already in use
-
-
Method Details
-
setDeletePolicy
Set the deletion policy.- Parameters:
policy
- either TaskQueue.DeletePolicy.MUST_BE_EMPTY, TaskQueue.DeletePolicy.WHEN_EMPTY, TaskQueue.DeletePolicy.NEVER; WHEN_EMPTY is the default
-
getDeletePolicy
Get the current deletion policy for the queue.- Returns:
- the current deletion policy
-
canDelete
public boolean canDelete()Determine if this named object can be deleted. A named object can be deleted if the method delete has not been called and if the object is not in a state that prevents the object from being deleted. Subclasses that override this method must call canDelete() for their superclasses and return false if the superclass' canDelete method returns false. The default method returns true if delete() has not been called and returned true.- Specified by:
canDelete
in interfaceNamedObjectOps
- Returns:
- true if this object can be deleted; false otherwise
-
onDelete
protected void onDelete()Complete the actions necessary to delete a named object. A subclass that overrides this method must call super.onDelete() at some point to complete the object deletion. This may not be within the onDelete method of the subclass if the deletion must be delayed for some reason (e.g., until some processing that is in progress has been completed). Once called, the object will be removed from the object-namer's tables and the object will be marked as deleted, so in general cleanup actions by a subclass should occur before it calls super.onDelete(). -
setEventParameters
Set an event's parameters. This method is provided because a field in the event class that has to be altered is not public.- Parameters:
event
- the eventparameters
- the parameters
-
init
protected void init()Method to provide additional initializations. This will be called by the TaskQueue constructor. The default method does nothing, but may be overridden (e.g., for initialization in an anonymous class). One reason to implement this method is to callsetCanFreeze(boolean)
and/orsetCanRelease(boolean)
when an anonymous class is initialized. -
addObserver
Description copied from interface:QueueStatus
Add an observer.- Specified by:
addObserver
in interfaceQueueStatus
- Parameters:
observer
- the observer
-
removeObserver
Description copied from interface:QueueStatus
Remove an observer.- Specified by:
removeObserver
in interfaceQueueStatus
- Parameters:
observer
- the observer
-
offerToQueue
Put an event on the queue. This method should be implemented by subclasses, which should also provide a queue on which to store an event. Normally an event is just added to the end of the queue. For some cases (e.g., a LIFO queue), one may need to preempt a currently scheduled event. If preemption is necessary, the preempted event's time parameters will have to be adjusted and the new event will have to become the scheduled event. The latter operation is handled byreplaceScheduledEvent
. If replaceScheduledEvent is used, care must be taken if the queue insertion could fail (e.g., the case of a finite-sized queue). For modifying the event parameters (e.g., to allow for time already attributed to processing an event), the methodsgetOffQueueTime
andgetEventParameters
may be useful.- Parameters:
event
- the eventscheduled
- the event that is currently scheduled for processing; null if there is none or if preempt mode is turned off- Returns:
- true if an event was successfully added to the queue; false otherwise
-
pollFromQueue
Take an event off the queue. This method should be implemented by subclasses, which should also provide a queue on which to store an event.- Returns:
- the event; null if the queue is empty
-
getOffQueueTime
Get the simulation time at which a TaskQueueSimEvent was removed from a queue. This is may be needed by the offerToQueue methods of subclasses when a scheduled event is replaced and the time needs to be adjusted before putting it back on the queue.- Parameters:
event
- the event that was removed from a queue- Returns:
- the last time the event was removed from a queue
-
getEventParameters
Get TaskQueueSimEvent parameters. This is may be needed by the offerToQueue methods of subclasses when a scheduled event is replaced.- Parameters:
event
- an event- Returns:
- the parameter field of the event
-
doAdd
protected TaskQueueSimEvent<T> doAdd(Callable callable, T parameters, long interval, double tpriority) Queue an event given a Callable and time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T.- Parameters:
callable
- the Callable specifying the task to be queued.parameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the Callable cannot be queued
-
doAdd
protected TaskQueueSimEvent<T> doAdd(SimObjectCallable callable, T parameters, long interval, double tpriority) Queue an event given a Callable bound to a simulation object and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T.- Parameters:
callable
- the SimObjectCallable specifying the task to be queued.parameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the Callable cannot be queued
-
doAddCallScript
protected TaskQueueSimEvent<T> doAddCallScript(String script, T parameters, long interval, double tpriority) throws RuntimeException, UnsupportedOperationException Queue an event given a script, a processing-time interval, and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T. Once scheduled, the script will be evaluated.- Parameters:
script
- the script to call when the entry is taken off the head of the queueparameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the script cannot be queued
- Throws:
RuntimeException
- if an exception occurred while trying to execute a script object'scall
methodUnsupportedOperationException
- if there is no script engine
-
doAddCallObject
protected TaskQueueSimEvent<T> doAddCallObject(Object scriptObject, T parameters, long interval, double tpriority) throws UnsupportedOperationException, RuntimeException Queue an event given a script object, a processing interval, and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T. Once scheduled to run, the object'scall()
method will be invoked.- Parameters:
scriptObject
- the script object whosecall()
method will be invokedparameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the object cannot be queued
- Throws:
RuntimeException
- if an exception occurred while trying to execute a script object'scall
methodUnsupportedOperationException
- if there is no script engine
-
doAdd
protected TaskQueueSimEvent<T> doAdd(Runnable runnable, T parameters, long interval, double tpriority) Queue an event given a Runnable, a processing-time interval, and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T.- Parameters:
runnable
- the Runnable specifying the task to be queued.parameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the Runnable cannot be queued
-
doAdd
protected TaskQueueSimEvent<T> doAdd(SimObjectRunnable runnable, T parameters, long interval, double tpriority) Queue an event given a Runnable bound to a simulation object and given a processing-time interval and time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T.- Parameters:
runnable
- the SimObjectRunnable specifying the task to be queued.parameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the Runnable cannot be queued
-
doAddTaskScript
protected TaskQueueSimEvent<T> doAddTaskScript(String script, T parameters, long interval, double tpriority) throws UnsupportedOperationException Queue a task that will run a script given a processing-time interval and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T. Once scheduled, the script will be evaluated.- Parameters:
script
- the script that will be run as a task.parameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the script cannot be queued
- Throws:
UnsupportedOperationException
-
doAddTaskObject
protected TaskQueueSimEvent<T> doAddTaskObject(Object scriptObject, T parameters, long interval, double tpriority) throws UnsupportedOperationException Queue a script object that will run a task, given a processing-time interval and a time event priority. This should be called by a subclass to add an event to a queue, as the currently scheduled event is handled specially. The subclass is responsible for using its "add" method's arguments to construct an instance of type T. Once scheduled, the object'srun()
method will be invoked.- Parameters:
scriptObject
- the script script object to queueparameters
- the parameters used in queuing or scheduling the requestinterval
- the processing-time interval implied by the parameterstpriority
- the time event priority implied by the parameters- Returns:
- the simulation event on success; null if the object cannot be queued
- Throws:
UnsupportedOperationException
-
replaceScheduledEvent
Replace the currently scheduled event. This has to effect when preempt mode is off. When preempt mode is on, the replacement becomes the currently scheduled event and the previous scheduled event, if any, is descheduled. This method is intended for use in calls to offerToQueue when the new event should be run and the previously scheduled event should be put back on the queue. In this case, offerToQueue may have to adjust the processing-time interval for the event, typically reducing this interval by the amount the event has already waited.- Parameters:
replacement
- the new event
-
addCurrentTask
Add the currently running task thread to a queue. This is public because the type parameter T may be a type for which autoboxing is possible. Otherwise it is usually more convenient for a subclass to implement a method that simply calls this method, with arguments providing data that will allow an object of type T to be constructed.- Parameters:
param
- the parameters used to determine how a queue insertion is done and how long to wait before the task is restarted once scheduled- Returns:
- true on success; false on failure in which case the current thread will continue to run
- Throws:
IllegalStateException
-
addCurrentTask
Add the currently running task thread to a queue. This is public because the type parameter T may be a type for which autoboxing is possible. Otherwise it is usually more convenient for a subclass to implement a method that simply calls this method, with arguments providing data that will allow an object of type T to be constructed in addition the the SimEventCallable argument.When the second argument (callable) is non-null and if queuing was successful, this argument will be passed to the second argument of
TaskThread.pause
to provide an opportunity to store the event so that the task can be canceled from the queue.- Parameters:
param
- the parameters used to determine how a queue insertion is done and how long to wait before the task is restarted once scheduledcallable
- this argument's call method will be run when the event is scheduled or queued and will be passed a simulation event (e.g., to store the event to allow the event to be canceled)- Returns:
- true on success; false on failure in which case the current thread will continue to run
-
addCurrentTaskObject
Add the currently running task thread to a queue and return the simulation event generated. This method is provided for convenience, especially for use in a script where a simpler, but slightly less efficient interface can be useful when a task may have to be canceled. This is public because the type parameter T may be a type for which autoboxing is possible. Otherwise it is usually more convenient for a subclass to implement a method that simply calls this method, with arguments providing data that will allow an object of type T to be constructed.- Parameters:
param
- the parameters used to determine how a queue insertion is done and how long to wait before the task is restarted once scheduled- Returns:
- a simulation event on success; null on failure in which case the current thread will continue to run
-
setCanFreeze
protected void setCanFreeze(boolean value) Set whether a queue can be frozen. Subclasses should call this method to change the default or to change whether or not the queue can be frozen. Normally it will called in a constructor, if at all.- Parameters:
value
- true if the queue can be frozen; false if it cannot
-
canFreeze
public boolean canFreeze()Determine if a queue can be frozen. If this returns false, the methodfreeze()
will throw an exception- Specified by:
canFreeze
in interfaceQueueStatus
- Returns:
- true if a queue can be frozen; false otherwise
- See Also:
-
freeze
Sets whether a queue is frozen or not. Freezing a queue means that all new entries go onto the queue rather than the first available being immediately scheduled.- Parameters:
value
- true if the queue will be frozen; false if unfrozen- Throws:
UnsupportedOperationException
- the queue can not be frozen- See Also:
-
forceFreeze
protected void forceFreeze(boolean value) Sets whether a queue is frozen or not regardless of the value returned by canFreeze. Freezing a queue means that all new entries go onto the queue rather than the first available being immediately scheduled. This method is intended to allow subclasses to manipulate whether a queue is frozen or not in cases where that operation is not allowed in general.- Parameters:
value
- true if the queue will be frozen; false if unfrozen- See Also:
-
isFrozen
public boolean isFrozen()Determine if a queue is frozen.- Specified by:
isFrozen
in interfaceQueueStatus
- Returns:
- true if it is frozen; false otherwise
- See Also:
-
canRelease
public boolean canRelease()- Returns:
- true if the methods release, releaseUpTo, and clearReleaseCount are supported; false otherwise
-
setReleasePolicy
public void setReleasePolicy(TaskQueue.ReleasePolicy policy) throws UnsupportedOperationException, IllegalStateException Set the release policy. The policy will have no effect ifcanRelease()
returns false.- Parameters:
policy
- either CANCEL_AS_RELEASED, CANCELS_IGNORED, or REPLACE_CANCELS- Throws:
UnsupportedOperationException
- the operation is not supported due to the value returned by canRelease()IllegalStateException
- a release operation was in progress
-
getReleasePolicy
Get the current release policy.- Returns:
- the current release policy
-
forceSetReleasePolicy
Forcibly set the release policy- Parameters:
policy
- the policy
-
setCanRelease
protected void setCanRelease(boolean value) Set whether or not the methodsrelease
,releaseUpTo
, andclearReleaseCount
are supported. By default, these methods are not supported.- Parameters:
value
- true if the methodsrelease
,releaseUpTo
, andclearReleaseCount
are supported; false otherwise
-
release
Allow a fixed number of entries to be removed from a queue even if the queue is frozen.- Parameters:
count
- the number of additional queue entries that are guaranteed to be processed regardless of whether the queue is frozen or not- Throws:
UnsupportedOperationException
- queue entries cannot be released
-
forceRelease
protected void forceRelease(int count) Allow a fixed number of entries to be removed from a queue even if the queue is frozen and even if canRelease() returns false. This method is intended to allow subclasses to process entries on a queue in cases where this operation is not allowed in general.- Parameters:
count
- the number of additional queue entries that are guaranteed to be processed regardless of whether the queue is frozen or not- See Also:
-
releaseUpTo
Allow a fixed number of entries up to the current queue size to be removed from a queue even if the queue is frozen.- Parameters:
count
- the number of additional queue entries that are requested to be processed regardless of whether the queue is frozen or not- Throws:
UnsupportedOperationException
- queue entries cannot be released
-
forceReleaseUpTo
protected void forceReleaseUpTo(int count) Allow a fixed number of entries up to the current queue size to be removed from a queue even if the queue is frozen. This method is intended to allow subclasses to process entries on a queue in cases where this operation is not allowed in general.- Parameters:
count
- the number of additional queue entries that are requested to be processed regardless of whether the queue is frozen or not
-
clearReleaseCount
Set the number of queued entries guaranteed that will be processed regardless of whether the queue is frozen to zero, provide release operations are supported- Throws:
UnsupportedOperationException
- queue entries cannot be released- See Also:
-
forceClearReleaseCount
protected void forceClearReleaseCount()Set the number of queued entries guaranteed that will be processed regardless of whether the queue is frozen to zero. This method is intended to allow subclasses to process entries on a queue in cases where this operation is not allowed in general. -
canPreempt
public boolean canPreempt()Determine if a a task queue supports preempt mode.- Returns:
- true if preempt mode is supported; false otherwise
- See Also:
-
preempt
Set preempt mode. When preempt mode is off, the new queue entries cannot preempt an event that has been removed from the queue for processing. If preempt mode is on, a currently scheduled event may be put back on the queue, with its processing-time adjusted appropriately and the new event processed instead.- Parameters:
value
- true to turn on preempt mode; false to turn it off- Throws:
UnsupportedOperationException
-
pauseCurrentTask
Suspend the currently running task thread. While the current task is suspended using this method, the queue does not schedule a new event. If TaskThread.pause is used instead, the queue will start processing new events and calling this method from the thread that called TaskThread.pause will result in an error.- Parameters:
interval
- the interval for which the task-thread will wait.- Throws:
IllegalStateException
- the thread is not the queue's current thread
-
pauseCurrentTask
Suspend the currently running task thread while it is still the scheduled event. While suspended, the queue does not schedule a new event. If TaskThread.pause is used instead, the queue will start processing new events, and calling this method from the thread that called TaskThread.pause without first requeuing the task will result in an error.- Parameters:
interval
- the interval for which the task-thread will wait.callable
- this argument's call method will be run when the event is scheduled and will be passed a simulation event (e.g., to store the event to allow the event to be canceled)- Throws:
IllegalStateException
- the thread is not the queue's current thread
-
tryRemove
Try to remove an event from the queue. By default, this method simply returns. This may be overridden by subclasses to allow events to be removed from a queue. The default behavior is to simply ignore events that are in a "canceled" state (and in this case, tryRemove always returns false). If the queue's data structure allows quick removal, implementing this method may improve efficiency in that case.- Parameters:
event
- the event to remove.- Returns:
- true if the event was removed or was not in the queue; false otherwise
-
getSize
protected abstract int getSize()Get the raw size of the queue. The size does not include the currently scheduled event. It does contain any events that were canceled but could not be removed.- Returns:
- the queue size
-
size
public int size()Get the size of the queue. The size does not include the currently scheduled event.- Specified by:
size
in interfaceQueueStatus
- Returns:
- the queue size
-
getInterval
Find the interval used to schedule a queue entry based on entry's parameters or a default value.- Parameters:
parameters
- the parameters for a queue entry- Returns:
- the interval in units of simulation ticks
-
getTPriority
Find the time event priority used to schedule a queue entry based on the entry's parameters or a default value of 0.0.- Parameters:
parameters
- the parameters for a queue entry- Returns:
- the priority
-
isBusy
public boolean isBusy()Determine if the queue is busy. A queue is busy if there is a scheduled event that is either running or on the simulation event queue, instead of stored in the queue.- Specified by:
isBusy
in interfaceQueueStatus
- Returns:
- true if the queue is busy; false otherwise
-
isProcessing
public boolean isProcessing()Determine if a scheduled queue entry is being processed. This is true when a callable, runnable, or task (that was scheduled after being pulled off the queue) is running.- Returns:
- true if being processed; false otherwise
-
inUseCount
public int inUseCount()Determine how many servers are in use. The default implementation allows only 1.- Specified by:
inUseCount
in interfaceQueueStatus
- Returns:
- the number of servers in use
-
serverCount
public int serverCount()Determine the maximum number of tasks or calls that can be handled concurrently (equivalent to the number of servers in a queuing system). The default implementation just returns 1.- Specified by:
serverCount
in interfaceQueueStatus
- Returns:
- the number that can be processed simultaneously
-
printConfiguration
In addition, the configuration that is printed includes the following: Print this simulation object's configuration. Documentation for the use of this method is provided by the documentation for theSimObject
methodSimObject.printConfiguration(String,String,boolean,PrintWriter)
.When the third argument has a value of true, the object name and class name will be printed in a standard format with its indentation provided by the iPrefix argument. In addition, the configuration that is printed includes the following.
Defined in
TaskQueue
:- the deletion policy.
- whether or not the queue can be frozen.
- the release policy.
- the concurrency limit.
- whether or not preemption is allowed.
- Overrides:
printConfiguration
in classDefaultSimObject
- Parameters:
iPrefix
- the prefix to use for an initial line when printName is true with null treated as an empty stringprefix
- a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is trueprintName
- requests printing the name of an objectout
- the output print writer
-
printState
Print this simulation object's state. Documentation for the use of this method is provided by the documentation for theSimObject
methodSimObject.printState(String,String,boolean,PrintWriter)
.When the second argument has a value of true, the object name and class name will be printed in a standard format with its indentation provided by the iPrefix argument. In addition, the state that is printed includes the following.
Defined in
TaskQueue
:- the queue size.
- whether or not the queue is frozen.
- the release count.
- whether or not the queue is busy.
- whether or not the queue is processing entries.
- the number of 'customers' being serviced.
- the current release policy.
- Overrides:
printState
in classDefaultSimObject
- Parameters:
iPrefix
- the prefix to use for an initial line when printName is true with null treated as an empty stringprefix
- a prefix string (typically whitespace) to put at the start of each line other than the initial line that is printed when printName is trueprintName
- requests printing the name of an objectout
- the output print writer
-
clone
Creates and returns a copy of this object. This method will throw the exception CloneNotSupportedException if the object is interned.- Overrides:
clone
in classObject
- Throws:
CloneNotSupportedException
- a clone could not be created- See Also:
-
isInterned
public boolean isInterned()Determine if an object is interned in a object namer's tables.- Specified by:
isInterned
in interfaceNamedObjectOps
- Returns:
- true if the object is interned; false if not
-
getObjectNamer
Get the object namer for a named object.- Returns:
- the object namer for this named object
-
getName
Get an object's name.- Specified by:
getName
in interfaceNamedObjectOps
- Returns:
- the name of the object
-
delete
public final boolean delete()Delete an object. An object can only be deleted once. If this method returns true, the object (if interned) will have been removed from the object namer tables.The implementations provided by
DefaultNamedObect
and generated because of a@NamedObject
annotation provide a protected method named onDelete. A subclass that overrides onDelete() must call the onDelete method of its superclass after it's onDelete method has been called and any cleanup actions performed. In some cases, this may happen at a later time (e.g., if a thread is used for some of the cleanup operations or if it is otherwise necessary to wait).- Specified by:
delete
in interfaceNamedObjectOps
- Returns:
- true if the deletion request was accepted; false otherwise
-
isDeleted
public final boolean isDeleted()Determine if an object has been deleted. An object is deleted if the method delete() has been called and returned true.- Specified by:
isDeleted
in interfaceNamedObjectOps
- Returns:
- true if deleted; false otherwise
-
deletePending
public final boolean deletePending()Determine if an object is being deleted. An deletion is pending if the method delete() has been called and returned true but the deletion has not been completed.- Specified by:
deletePending
in interfaceNamedObjectOps
- Returns:
- true if deletion is pending; false otherwise
-