public interface SimQueue<J extends SimJob,Q extends SimQueue> extends SimEntity, SimQoS<J,Q>
SimJobs).
A SimQueue is an abstraction of a queueing system from queueing theory.
The following javadoc section aims at concisely specifying the SimQueue interface.
The assumptions and constraints in the sequel should not be interpreted as "agreed upon in the field",
but motivations for them are not given here in order to keep the section at (hopefully) pleasant length.
A SimQueue accepts so-called jobs (in our case SimJobs) for a visit.
Each job can visit at most one queue at a time,
and while it is visiting a queue,
it cannot initiate another visit to that same queue.
A visit is initiated by the arrival of a job at a queue, see arrive(double, J).
During a visit, a job is either in the queue's so-called waiting area, in which it always waits, or in the queue's service area, in which the job can receive service from the servers in the service area. At the beginning of a visit (the arrival), a job is either put in the waiting area or directly into the service area (or dropped immediately). A job can move at most once from the waiting into the service area, but not in reverse direction. Entering the service area of a queue is called starting the job.
In itself, a SimQueue makes no assumption whatsoever about the server structure,
except for the fact that only jobs in the service area can receive service.
But other than that, there may be any number (including zero and infinity) of servers,
and the number of servers may change in time in the SimQueue interface.
This flexibility, however, comes at the expense of the absence of server-structure methods
on the (bare) SimQueue interface.
Also note that jobs in the service area do not have to be served all the time (although many sub-interfaces/sub-classes impose this requirement).
A visit can end in three different ways:
If a visit ends, the job is said to exit (depart from; be dropped at; be (auto-)revoked at) the queue. Each way to exit the queue can be from the waiting area or from the service area (but sub-classes may restrict the possibilities).
If a visit never ends, the job (or the visit) is named sticky; again this can be at the waiting area or the service area.
Each SimQueue must support the notions of queue-access vacations during which all jobs are dropped upon arrival,
and of server-access credits that limit the remaining number of jobs that can be started
(i.e., moved from the waiting area into the service area).
The state of a SimQueue includes at least the set of jobs present (and in which area each resides),
its queue-access vacation state and its remaining number of server-access credits.
In addition, the so-called startArmed state has to be maintained, see isStartArmed().
Each SimQueue (and SimJob for that matter) must notify all state changes,
see SimEntityListener.
A partial implementation of SimQueue is available in AbstractSimQueue.
Copyright (C) 2005-2017 Jan de Jongh, TNO
This file is covered by the LICENSE file in the root of this project.
SimEventList,
SimEntity,
SimJob,
SimQueueListener,
AbstractSimQueue| Modifier and Type | Interface and Description |
|---|---|
static class |
SimQueue.AutoRevocationPolicy
The auto-revocation policy.
|
SimEntity.Action, SimEntity.UnknownNotificationTypePolicy, SimEntity.UnknownOperationPolicy| Modifier and Type | Method and Description |
|---|---|
void |
arrive(double time,
J job)
Arrival of a job at the queue.
|
SimQueue.AutoRevocationPolicy |
getAutoRevocationPolicy()
Gets the auto-revocation policy of this queue.
|
SimQueue<J,Q> |
getCopySimQueue()
Creates a functional copy of this
SimQueue. |
Set<J> |
getJobs()
Gets the set of jobs currently visiting this queue.
|
Set<J> |
getJobsInServiceArea()
Get the set of jobs in the service area.
|
Set<J> |
getJobsInWaitingArea()
Get the set of jobs in the waiting area.
|
int |
getNumberOfJobs()
Gets the number of jobs currently visiting the queue.
|
int |
getNumberOfJobsInServiceArea()
Gets the number of jobs in the service area.
|
int |
getNumberOfJobsInWaitingArea()
Gets the number of jobs in the waiting area.
|
int |
getServerAccessCredits()
Gets the (remaining) server-access credits.
|
boolean |
isJob(SimJob job)
Checks for the presence of a job.
|
boolean |
isJobInServiceArea(SimJob job)
Checks for the presence of a job in the service area.
|
boolean |
isJobInWaitingArea(SimJob job)
Checks for the presence of a job in the waiting area.
|
boolean |
isQueueAccessVacation()
Returns whether or not the queue is on queue-access vacation.
|
boolean |
isStartArmed()
Returns the
StartArmed state of the queue. |
default void |
revoke(double time,
J job)
Revocation of a job at a queue.
|
boolean |
revoke(double time,
J job,
boolean interruptService)
Revocation (attempt) of a job at a queue.
|
void |
setAutoRevocationPolicy(SimQueue.AutoRevocationPolicy autoRevocationPolicy)
Sets the auto-revocation policy of this queue.
|
void |
setQueueAccessVacation(double time,
boolean start)
Starts or ends a queue-access vacation.
|
void |
setServerAccessCredits(double time,
int credits)
Sets the server-access credits.
|
doAfterNotifications, doOperation, getEventList, getLastUpdateTime, getRegisteredNotificationTypes, getRegisteredOperations, getSimEntityListeners, getUnknownNotificationTypePolicy, getUnknownOperationPolicy, isIgnoreEventListReset, registerSimEntityListener, resetEntity, setIgnoreEventListReset, setName, setUnknownNotificationTypePolicy, setUnknownOperationPolicy, toStringDefault, unregisterSimEntityListener, updatenotifyEventListResetgetQoS, getQoSClassSimQueue<J,Q> getCopySimQueue() throws UnsupportedOperationException
SimQueue.
The new object has the same (concrete) type as the original, but starts without jobs and without external listeners.
Its initial state must be as if SimEntity.resetEntity() was invoked on the queue.
Note that the semantics of this method are much less strict than the Object.clone () method.
Typically, concrete classes will implement this by returning a new SimQueue object.
This way, we circumvent the problem of cloning objects with final (for good reasons) fields.
SimQueue.UnsupportedOperationException - If the operation is not supported (yet); this should be considered a software error.Set<J> getJobs()
null.getNumberOfJobs(),
getJobsInWaitingArea(),
getJobsInServiceArea()int getNumberOfJobs()
Typically, this method is more efficient than getJobs ().size (),
but both methods must always yield the same result.
getJobs(),
getNumberOfJobsInWaitingArea(),
getNumberOfJobsInServiceArea()boolean isJob(SimJob job)
Typically, this method is more efficient than getJobs ().contains (job),
but both methods must always yield the same result.
job - The job.getJobs()Set<J> getJobsInWaitingArea()
null.getNumberOfJobsInWaitingArea(),
getJobs(),
getJobsInServiceArea()int getNumberOfJobsInWaitingArea()
Typically, this method is more efficient than getJobsInWaitingArea ().size (),
but both methods must always yield the same result.
getJobsInWaitingArea(),
getNumberOfJobs(),
getNumberOfJobsInServiceArea()boolean isJobInWaitingArea(SimJob job)
Typically, this method is more efficient than getJobsInWaitingArea ().contains (job),
but both methods must always yield the same result.
job - The job.getJobsInWaitingArea()Set<J> getJobsInServiceArea()
null.getNumberOfJobsInServiceArea(),
getJobs(),
getJobsInWaitingArea()int getNumberOfJobsInServiceArea()
Typically, this method is more efficient than getJobsInServiceArea ().size (),
but both methods must always yield the same result.
getJobsInServiceArea(),
getNumberOfJobs(),
getNumberOfJobsInWaitingArea()boolean isJobInServiceArea(SimJob job)
Typically, this method is more efficient than getJobsInServiceArea ().contains (job),
but both methods must always yield the same result.
job - The job.getJobsInWaitingArea()boolean isQueueAccessVacation()
setQueueAccessVacation(double, boolean)void setQueueAccessVacation(double time,
boolean start)
During a queue-access vacation, all SimJobs will be dropped immediately upon arrival.
time - The time at which to start or end the queue-access vacation, i.c., the current time.start - Whether to start (true) or end (false) the vacation.arrive(double, J),
isQueueAccessVacation()void arrive(double time,
J job)
This methods should be called from the SimEventList as a result of scheduling the job arrival.
Implementations can rely on the fact that the time argument supplied is actually the current time in the simulation.
Do not use this method to schedule job arrivals on the event list!
Note that during a queue-access vacation, all jobs will be dropped upon arrival.
time - The time at which the job arrives, i.c., the current time.job - The job.isQueueAccessVacation()boolean revoke(double time,
J job,
boolean interruptService)
If the job is not currently present at this SimQueue, false is returned.
If the job is present in the service area (has already started), and interruptService == false,
this method returns false.
In all other case, the job is revoked from the queue and true is returned.
time - The time at which the request is issued, i.c., the current time.job - The job to be revoked from the queue.interruptService - Whether to allow interruption of the job's
service if already started.
If false, revocation will only succeed if the
job has not started yet.false if the job is not present).default void revoke(double time,
J job)
Unlike revoke(double, SimJob, boolean), this request can never fail
in the sense that upon return from this method, the job is no longer present in the queue.
This method does nothing if the job is not present a priori at the queue.
time - The time at which the request is issued, i.c., the current time.job - The job to be revoked from the queue.SimQueue.AutoRevocationPolicy getAutoRevocationPolicy()
SimQueue.AutoRevocationPolicyvoid setAutoRevocationPolicy(SimQueue.AutoRevocationPolicy autoRevocationPolicy)
The auto-revocation policy on a queue should be set only once and before the queue's use. It must survive queue resets.
autoRevocationPolicy - The new auto-revocation policy, non-null.IllegalArgumentException - If the policy is null.SimQueue.AutoRevocationPolicyint getServerAccessCredits()
The number of server-access credits is the remaining number of jobs allowed to start.
They play an essential role in composite queues, notably CTandem2.
Upon reset, the initial value must be Integer.MAX_VALUE,
which is treated as infinity.
Integer.MAX_VALUE treated as infinity.setServerAccessCredits(double, int)void setServerAccessCredits(double time,
int credits)
time - The time at which to set the credits, i.c., the current time.credits - The new remaining server-access credits, non-negative, with Integer.MAX_VALUE treated as infinity.IllegalArgumentException - If credits is (strictly) negative.getServerAccessCredits()boolean isStartArmed()
StartArmed state of the queue.
Formally: A queue is in StartArmed state,
and this method returns true,
if and only if any (hypothetical) arriving job will start service immediately
(i.e., enter the service area upon arrival immediately),
assuming the following (i.e., ignoring the actual state settings):
Note that the actual values of the state properties above is irrelevant.
Informally, the StartArmed state of a queue reflects the fact that not all service capacity
of the queue is used at the present time (for whatever reason);
not used to such an extent that the queue would start an arriving job immediately
if the three requirements mentioned above would hold.
The StartArmed state of a queue is admittedly difficult to grasp and unlikely to find many uses in practice,
but it is essential for specific types of so-called composite queues,
i.e., queues that are composed of other queues.
See, for instance, CTandem2.
StartArmed state.SimQueueListener.notifyNewStartArmed(double, Q, boolean)Copyright © 2018. All rights reserved.