org.javades.jqueues.r5.entity.jq.queue.qos

Class HOL<J extends SimJob,Q extends HOL,P extends Comparable>

java.lang.Object

org.javades.jqueues.r5.entity.AbstractSimEntity

org.javades.jqueues.r5.entity.jq.AbstractSimJQ<J,Q>

org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue<J,Q>

org.javades.jqueues.r5.entity.jq.queue.qos.AbstractSimQueueQoS<J,Q,P>

org.javades.jqueues.r5.entity.jq.queue.qos.HOL<J,Q,P>

Type Parameters:

J - The type of SimJobs supported.

Q - The type of SimQueues supported.

P - The type used for QoS.

All Implemented Interfaces:

SimQueue<J,Q>, SimQoS<J,Q>, SimEntity, SimQueueOrJobQoS<J,Q,P>, SimQueueQoS<J,Q,P>, org.javades.jsimulation.r5.SimEventListResetListener

public class HOL<J extends SimJob,Q extends HOL,P extends Comparable>
extends AbstractSimQueueQoS<J,Q,P>
implements SimQueueQoS<J,Q,P>

The Head-of-the-Line (HOL) queueing discipline.

Author:

Jan de Jongh, TNO

Copyright (C) 2005-2017 Jan de Jongh, TNO

This file is covered by the LICENSE file in the root of this project.

Nested Class Summary

Nested classes/interfaces inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

AbstractSimEntity.Notifier, AbstractSimEntity.PreNotificationHook

Nested classes/interfaces inherited from interface org.javades.jqueues.r5.entity.jq.queue.SimQueue

SimQueue.AutoRevocationPolicy

Nested classes/interfaces inherited from interface org.javades.jqueues.r5.entity.SimEntity

SimEntity.Action, SimEntity.UnknownNotificationTypePolicy, SimEntity.UnknownOperationPolicy

Field Summary

Fields

Modifier and Type	Field and Description
protected NavigableMap<P,Set<J>>	jobsQoSMap

Fields inherited from class org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue

eventsScheduled, SANITY

Fields inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

USE_ARRAY_OPTIMIZATION

Constructor Summary

Constructors

Constructor and Description
HOL(org.javades.jsimulation.r5.SimEventList eventList, Class<P> qosClass, P defaultJobQoS) Creates a new HOL.

Method Summary

Modifier and Type	Method and Description
HOL<J,Q,P>	getCopySimQueue() Returns a new HOL object on the same SimEventList with the same QoS structure.
NavigableMap<P,Set<J>>	getJobsQoSMap() Gets the mapping QoS values onto jobs currently visiting this queue with that particular QoS value.
protected J	getNextJobToServeInWaitingArea() Gets the job in the waiting area that is next to serve.
protected double	getServiceTimeForJob(J job) Calls super method (in order to make implementation final).
protected void	insertJobInQueueUponArrival(J job, double time) Inserts the job jobsQoSMap.
protected void	insertJobInQueueUponStart(J job, double time) Performs sanity checks (only).
boolean	isStartArmed() Returns true if there are no jobs present in the service area.
protected void	removeJobFromQueueUponDeparture(J departingJob, double time) Removes the departing job from jobsQoSMap.
protected void	removeJobFromQueueUponDrop(J job, double time) Throws an IllegalStateException because drops are unexpected.
protected void	removeJobFromQueueUponRevokation(J job, double time, boolean auto) Removes the job from the internal data structures, and if needed, cancels a pending departure event.
protected void	rescheduleAfterArrival(J job, double time) Starts the arrived job if server-access credits are available and if there are no jobs in the service area.
protected void	rescheduleAfterDeparture(J departedJob, double time) Starts the next job in the waiting area (if available) if server-access credits are available.
protected void	rescheduleAfterDrop(J job, double time) Throws an IllegalStateException because drops are unexpected.
protected void	rescheduleAfterRevokation(J job, double time, boolean auto) Starts the next job in the waiting area if server-access credits are available and if there are no jobs in the service area.
protected void	rescheduleAfterStart(J job, double time) Depending on the job's requested service time, makes it depart immediately, or schedules a suitable departure event.
protected void	rescheduleDepartureEvent() Reschedules the single departure event for this queue.
protected void	rescheduleForNewServerAccessCredits(double time) Starts the next job in the waiting area if there are no jobs in the service area.
protected void	resetEntitySubClass() Calls super method and clears jobsQoSMap.
protected void	setServerAccessCreditsSubClass() Calls super method (in order to make implementation final).
String	toStringDefault() Returns "HOL".

Methods inherited from class org.javades.jqueues.r5.entity.jq.queue.qos.AbstractSimQueueQoS

getDefaultJobQoS, getQoS, getQoSClass, queueAccessVacationDropSubClass, setQoS, setQoSClass

Methods inherited from class org.javades.jqueues.r5.entity.jq.queue.AbstractSimQueue

arrive, autoRevoke, cancelDepartureEvent, cancelDepartureEvent, depart, departureFromEventList, drop, getAutoRevocationPolicy, getDepartureEvents, getDepartureEvents, getFirstJob, getFirstJobInServiceArea, getFirstJobInWaitingArea, getJobs, getJobsInServiceArea, getJobsInWaitingArea, getNumberOfJobs, getNumberOfJobsInServiceArea, getNumberOfJobsInWaitingArea, getServerAccessCredits, hasJobs, hasJobsInServiceArea, hasJobsInWaitingArea, hasServerAcccessCredits, isJob, isJobInServiceArea, isJobInWaitingArea, isQueueAccessVacation, registerStdOutSimQueueListener, revoke, revoke, scheduleDepartureEvent, scheduleJobArrival, setAutoRevocationPolicy, setQueueAccessVacation, setServerAccessCredits, start, takeServerAccessCredit, triggerPotentialNewStartArmed, unregisterStdOutSimQueueListener

Methods inherited from class org.javades.jqueues.r5.entity.AbstractSimEntity

addPendingNotification, addPendingNotification, clearAndUnlockPendingNotificationsIfLocked, delegateOperation, doAfterNotifications, doOperation, fireAndLockPendingNotifications, getEventList, getLastUpdateTime, getRegisteredDelegatedOperations, getRegisteredNotificationTypes, getRegisteredOperations, getSimEntityListeners, getUnknownNotificationTypePolicy, getUnknownOperationPolicy, isIgnoreEventListReset, notifyEventListReset, registerDelegatedOperation, registerNotificationType, registerOperation, registerPreEventHook, registerPreNotificationHook, registerPreUpdateHook, registerSimEntityListener, registerStdOutSimEntityListener, removeDelegationForOperation, resetEntity, setIgnoreEventListReset, setName, setUnknownNotificationTypePolicy, setUnknownOperationPolicy, toString, unregisterSimEntityListener, unregisterStdOutSimEntityListener, update

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.javades.jqueues.r5.extensions.qos.SimQueueQoS

getDefaultJobQoS

Methods inherited from interface org.javades.jqueues.r5.extensions.qos.SimQueueOrJobQoS

getQoS, getQoSClass, setQoS, setQoSClass

Methods inherited from interface org.javades.jqueues.r5.entity.jq.queue.SimQueue

arrive, getAutoRevocationPolicy, getJobs, getJobsInServiceArea, getJobsInWaitingArea, getNumberOfJobs, getNumberOfJobsInServiceArea, getNumberOfJobsInWaitingArea, getServerAccessCredits, isJob, isJobInServiceArea, isJobInWaitingArea, isQueueAccessVacation, revoke, revoke, setAutoRevocationPolicy, setQueueAccessVacation, setServerAccessCredits

Methods inherited from interface org.javades.jqueues.r5.entity.SimEntity

doAfterNotifications, doOperation, getEventList, getLastUpdateTime, getRegisteredNotificationTypes, getRegisteredOperations, getSimEntityListeners, getUnknownNotificationTypePolicy, getUnknownOperationPolicy, isIgnoreEventListReset, registerSimEntityListener, resetEntity, setIgnoreEventListReset, setName, setUnknownNotificationTypePolicy, setUnknownOperationPolicy, unregisterSimEntityListener, update

Methods inherited from interface org.javades.jsimulation.r5.SimEventListResetListener

notifyEventListReset

Field Detail

jobsQoSMap

protected final NavigableMap<P extends Comparable,Set<J extends SimJob>> jobsQoSMap

Constructor Detail

HOL

public HOL(org.javades.jsimulation.r5.SimEventList eventList,
           Class<P> qosClass,
           P defaultJobQoS)

Creates a new HOL.

Parameters:

eventList - The event list to use, non-null.

qosClass - The Java class to use for QoS behavior, non-null.

defaultJobQoS - The default QoS value to use for non-QoS jobs, non-null.

Throws:

IllegalArgumentException - If any of the arguments is null.

Method Detail

getCopySimQueue

public HOL<J,Q,P> getCopySimQueue()
                           throws UnsupportedOperationException

Returns a new HOL object on the same SimEventList with the same QoS structure.

Specified by:

getCopySimQueue in interface SimQueue<J extends SimJob,Q extends HOL>

Specified by:

getCopySimQueue in interface SimQueueQoS<J extends SimJob,Q extends HOL,P extends Comparable>

Returns:

A new HOL object on the same SimEventList with the same QoS structure.

Throws:

UnsupportedOperationException - If the operation is not supported (yet); this should be considered a software error.

See Also:

AbstractSimEntity.getEventList(), AbstractSimQueueQoS.getQoSClass(), AbstractSimQueueQoS.getDefaultJobQoS()

toStringDefault

public String toStringDefault()

Returns "HOL".

Specified by:

toStringDefault in interface SimEntity

Overrides:

toStringDefault in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Returns:

"HOL".

See Also:

SimEntity.setName(java.lang.String), Object.toString()

getJobsQoSMap

public final NavigableMap<P,Set<J>> getJobsQoSMap()

Description copied from interface: SimQueueQoS

Gets the mapping QoS values onto jobs currently visiting this queue with that particular QoS value.

Each SimJob present returning (valid) non-null QoS value from SimQoS.getQoS() must be in present in only that value set, and the union of these value sets must exactly match SimQueue.getJobs(). Jobs returning null from SimQoS.getQoS() must be put in a value set corresponding to SimQueueQoS.getDefaultJobQoS().

Note that many concrete subclasses will impose an ordering on the keys and/or on the value sets.

Specified by:

getJobsQoSMap in interface SimQueueQoS<J extends SimJob,Q extends HOL,P extends Comparable>

Returns:

The mapping QoS values onto jobs currently visiting this queue with that particular QoS value.

See Also:

SimQueue.getJobs(), SimQoS.getQoS(), SimQueueQoS.getDefaultJobQoS()

getNextJobToServeInWaitingArea

protected final J getNextJobToServeInWaitingArea()

Gets the job in the waiting area that is next to serve.

Iterates over the job sets in increasing order of QoS value, and iterates over the jobs within each set in order as enforced by the standard Java Set iterator, and returns the first job it finds that is not in the service area.

This method does (some) sanity checks on jobsQoSMap on the fly.

Returns:

The job in the waiting area that is next to serve, null if there are no waiting jobs.

Throws:

IllegalStateException - If the jobsQoSMap is in an illegal state.

See Also:

jobsQoSMap, AbstractSimQueue.isJob(org.javades.jqueues.r5.entity.jq.job.SimJob), AbstractSimQueue.isJobInServiceArea(org.javades.jqueues.r5.entity.jq.job.SimJob)

resetEntitySubClass

protected final void resetEntitySubClass()

Calls super method and clears jobsQoSMap.

Overrides:

resetEntitySubClass in class AbstractSimQueueQoS<J extends SimJob,Q extends HOL,P extends Comparable>

See Also:

jobsQoSMap

insertJobInQueueUponArrival

protected final void insertJobInQueueUponArrival(J job,
                                                 double time)

Inserts the job jobsQoSMap.

Specified by:

insertJobInQueueUponArrival in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that arrived.

time - The current time (i.e., arrival time of the job).

See Also:

SimQueueQoSUtils.getAndCheckJobQoS(J, Q)

rescheduleAfterArrival

protected final void rescheduleAfterArrival(J job,
                                            double time)

Starts the arrived job if server-access credits are available and if there are no jobs in the service area.

Specified by:

rescheduleAfterArrival in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that arrived (and is already present in AbstractSimQueue.getJobs()).

time - The current time (i.e., the arrival time of the job).

See Also:

AbstractSimQueue.hasServerAcccessCredits(), AbstractSimQueue.hasJobsInServiceArea(), AbstractSimQueue.start(double, J)

removeJobFromQueueUponDrop

protected final void removeJobFromQueueUponDrop(J job,
                                                double time)

Throws an IllegalStateException because drops are unexpected.

Specified by:

removeJobFromQueueUponDrop in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that is to be dropped.

time - The current time (i.e., drop time of the job).

Throws:

IllegalStateException - Always.

See Also:

AbstractSimQueue.drop(J, double), AbstractSimQueue.rescheduleAfterDrop(J, double)

rescheduleAfterDrop

protected final void rescheduleAfterDrop(J job,
                                         double time)

Throws an IllegalStateException because drops are unexpected.

Specified by:

rescheduleAfterDrop in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The jobs that was dropped.

time - The current time (i.e., drop time of the job).

Throws:

IllegalStateException - Always.

See Also:

AbstractSimQueue.drop(J, double), AbstractSimQueue.removeJobFromQueueUponDrop(J, double)

removeJobFromQueueUponRevokation

protected final void removeJobFromQueueUponRevokation(J job,
                                                      double time,
                                                      boolean auto)

Removes the job from the internal data structures, and if needed, cancels a pending departure event.

If the job is in service, its departure event is canceled through AbstractSimQueue.cancelDepartureEvent(org.javades.jqueues.r5.entity.jq.SimJQEvent.Departure<J, Q>). Subsequently, whether the job was in service or not, it is removed from jobsQoSMap.

Specified by:

removeJobFromQueueUponRevokation in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that is to be revoked.

time - The current time (i.e., revocation time of the job).

auto - Whether or not this applies to an auto-revocation.

See Also:

AbstractSimQueue.cancelDepartureEvent(org.javades.jqueues.r5.entity.jq.SimJQEvent.Departure<J, Q>), jobsQoSMap

rescheduleAfterRevokation

protected final void rescheduleAfterRevokation(J job,
                                               double time,
                                               boolean auto)

Starts the next job in the waiting area if server-access credits are available and if there are no jobs in the service area.

Specified by:

rescheduleAfterRevokation in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The jobs that was successfully revoked.

time - The current time (i.e., revocation time of the job).

auto - Whether or not this applies to an auto-revocation.

See Also:

AbstractSimQueue.hasServerAcccessCredits(), AbstractSimQueue.hasJobsInWaitingArea(), AbstractSimQueue.getNumberOfJobsInServiceArea(), AbstractSimQueue.start(double, J), getNextJobToServeInWaitingArea()

setServerAccessCreditsSubClass

protected final void setServerAccessCreditsSubClass()

Calls super method (in order to make implementation final).

Overrides:

setServerAccessCreditsSubClass in class AbstractSimQueue<J extends SimJob,Q extends HOL>

See Also:

AbstractSimQueue.getServerAccessCredits(), AbstractSimQueue.setServerAccessCredits(double, int), AbstractSimQueue.rescheduleForNewServerAccessCredits(double)

rescheduleForNewServerAccessCredits

protected final void rescheduleForNewServerAccessCredits(double time)

Starts the next job in the waiting area if there are no jobs in the service area.

Specified by:

rescheduleForNewServerAccessCredits in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

time - The current time (i.e., the time at which new server-access credits became available).

See Also:

AbstractSimQueue.hasJobsInWaitingArea(), AbstractSimQueue.getNumberOfJobsInServiceArea(), AbstractSimQueue.start(double, J)

isStartArmed

public final boolean isStartArmed()

Returns true if there are no jobs present in the service area.

Specified by:

isStartArmed in interface SimQueue<J extends SimJob,Q extends HOL>

Returns:

True if there are no jobs present in the service area.

See Also:

AbstractSimQueue.getNumberOfJobsInServiceArea()

insertJobInQueueUponStart

protected final void insertJobInQueueUponStart(J job,
                                               double time)

Performs sanity checks (only).

Specified by:

insertJobInQueueUponStart in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that starts.

time - The current time (i.e., start time of the job).

See Also:

AbstractSimQueue.start(double, J), AbstractSimQueue.rescheduleAfterStart(J, double)

rescheduleAfterStart

protected final void rescheduleAfterStart(J job,
                                          double time)

Depending on the job's requested service time, makes it depart immediately, or schedules a suitable departure event.

Performs sanity checks on the fly (job present; job not yet started; requested service time zero or positive). The time argument must match the result from AbstractSimEntity.getLastUpdateTime() (and is thus only present for sanity checking).

If a job has infinite requested service time, it will start but never depart, even if the start is scheduled at positive or negative infinity.

With zero requested service time, a job departs immediately. This is also the case if the start is at positive or negative infinity AND the job has finite requested service time.

In all other cases, a suitable departure event is scheduled through rescheduleDepartureEvent().

Caveat: the specification above implies that NOT all jobs in the service area will have a departure event scheduled for them!

Specified by:

rescheduleAfterStart in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job that started (and is already present in AbstractSimQueue.getJobsInServiceArea().

time - The current time (i.e., the start time of the job).

See Also:

getServiceTimeForJob(J), rescheduleDepartureEvent(), AbstractSimQueue.depart(double, J)

getServiceTimeForJob

protected final double getServiceTimeForJob(J job)

Calls super method (in order to make implementation final).

Overrides:

getServiceTimeForJob in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

job - The job, non-null.

Returns:

The result from the super method.

removeJobFromQueueUponDeparture

protected final void removeJobFromQueueUponDeparture(J departingJob,
                                                     double time)

Removes the departing job from jobsQoSMap.

Specified by:

removeJobFromQueueUponDeparture in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

departingJob - The job that departs.

time - The departure (current) time.

Throws:

IllegalStateException - If the job is not in the map.

See Also:

jobsQoSMap

rescheduleAfterDeparture

protected final void rescheduleAfterDeparture(J departedJob,
                                              double time)

Starts the next job in the waiting area (if available) if server-access credits are available.

Specified by:

rescheduleAfterDeparture in class AbstractSimQueue<J extends SimJob,Q extends HOL>

Parameters:

departedJob - The departed job.

time - The departure (current) time.

Throws:

IllegalStateException - If there are jobs in the service area (i.e., being served).

See Also:

AbstractSimQueue.hasJobsInServiceArea(), AbstractSimQueue.hasServerAcccessCredits(), AbstractSimQueue.hasJobsInWaitingArea(), AbstractSimQueue.start(double, J), getNextJobToServeInWaitingArea()

rescheduleDepartureEvent

protected final void rescheduleDepartureEvent()

Reschedules the single departure event for this queue.

Cancels a pending departure event and schedules the first job in the service area for departure (if ever).

If the job has infinite requested service time, this method does nothing, even if the start is scheduled at positive or negative infinity.

With zero requested service time, the job departs immediately. This is also the case if time (AbstractSimEntity.getLastUpdateTime()) is at positive or negative infinity AND the job has finite requested service time.

In all other cases, a suitable departure event is scheduled through rescheduleDepartureEvent().

See Also:

AbstractSimQueue.getDepartureEvents(), AbstractSimQueue.cancelDepartureEvent(org.javades.jqueues.r5.entity.jq.SimJQEvent.Departure<J, Q>), AbstractSimQueue.jobsInServiceArea, AbstractSimQueue.getFirstJobInServiceArea(), getServiceTimeForJob(J), AbstractSimEntity.getLastUpdateTime(), AbstractSimQueue.scheduleDepartureEvent(double, J), AbstractSimQueue.depart(double, J), AbstractSimEntity.getLastUpdateTime()