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

Class CUPS<J extends SimJob,Q extends CUPS>

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.AbstractClassicSimQueue<J,Q>

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

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

Type Parameters:

J - The type of SimJobs supported.

Q - The type of SimQueues supported.

All Implemented Interfaces:

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

public class CUPS<J extends SimJob,Q extends CUPS>
extends AbstractProcessorSharingSimQueue<J,Q>

The "catch-up" single-server CUPS queue serves all jobs with the least obtained service time simultaneously, equally distributing its service capacity among them.

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

Modifier and Type	Class and Description
protected static class	CUPS.CatchUpEvent A schedule-able SimEvent for catch-ups of which a single instance is used throughout in this class.

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 CUPS.CatchUpEvent	catchUpEvent The single catch-up event.
static double	TOLERANCE_OST The tolerance for rounding errors in the obtained service time.

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
CUPS(org.javades.jsimulation.r5.SimEventList eventList) Creates a single-server CUPS queue with infinite buffer size given an event list.

Method Summary

Modifier and Type	Method and Description
protected void	cancelCatchUpEvent() Cancels a pending catch-up event (if scheduled).
protected void	catchUp(double time) Calls AbstractSimEntity.update(double) followed by rescheduleDepartureEvent() and rescheduleCatchUpEvent().
CUPS<J,Q>	getCopySimQueue() Returns a new CUPS object on the same SimEventList.
protected Set<J>	getJobsExecuting() Gets the jobs currently in execution.
protected double	getMinimumObtainedServiceTime() Returns the minimum obtained service time (i.e., of all the jobs currently in execution).
protected int	getNumberOfJobsExecuting() Gets the number of jobs in execution.
Object	getQoS() Calls super method (in order to make implementation final).
Class	getQoSClass() Calls super method (in order to make implementation final).
protected double	getServiceTimeForJob(J job) Calls super method (in order to make implementation final).
protected double	getTimeToCatchUp() Calculates the time until the next catch-up.
protected void	insertJobInQueueUponArrival(J job, double time) Does nothing, and makes that final.
protected void	insertJobInQueueUponStart(J job, double time) Performs sanity checks and administers the job's initial obtained service time.
boolean	isStartArmed() Returns true.
protected void	removeJobFromInternalAdministration(J job) Removes the given job, if present, from the internal administration.
protected void	removeJobFromQueueUponDeparture(J departingJob, double time) Calls removeJobFromQueueUponRevokation(J, double, boolean) for the departed job.
protected void	removeJobFromQueueUponDrop(J job, double time) Throws IllegalStateException.
protected void	removeJobFromQueueUponRevokation(J job, double time, boolean auto) Removes the jobs from the internal data structures.
protected void	rescheduleAfterArrival(J job, double time) Starts the arrived job if server-access credits are available.
protected void	rescheduleAfterDeparture(J departedJob, double time) Calls rescheduleDepartureEvent() and rescheduleCatchUpEvent().
protected void	rescheduleAfterDrop(J job, double time) Throws IllegalStateException.
protected void	rescheduleAfterRevokation(J job, double time, boolean auto) Calls rescheduleDepartureEvent() and rescheduleCatchUpEvent().
protected void	rescheduleAfterStart(J job, double time) Reschedules due to the start of a job, making it depart immediately if its requested service time is zero (or finite and time itself is infinite), or rescheduling through rescheduleDepartureEvent() and rescheduleCatchUpEvent() otherwise.
protected void	rescheduleCatchUpEvent() Reschedules a catch-up event.
protected void	rescheduleDepartureEvent() Reschedules the single departure event for this queue.
protected void	rescheduleForNewServerAccessCredits(double time) Starts jobs as long as there are server-access credits and jobs waiting.
protected void	resetEntitySubClass() Calls super method and clears the internal administration.
protected void	sanityInternalAdministration() Performs sanity checks on the internal administration.
protected void	setServerAccessCreditsSubClass() Calls super method (in order to make implementation final).
String	toStringDefault() Returns "CUPS".
protected void	updateObtainedServiceTime(double newTime) Updates the internal administration (i.c., obtained service times) for executing jobs in the service area.

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

queueAccessVacationDropSubClass

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

getBufferSize, getNumberOfServers

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.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

TOLERANCE_OST

public static final double TOLERANCE_OST

The tolerance for rounding errors in the obtained service time.

See Also:

Constant Field Values

catchUpEvent

protected final CUPS.CatchUpEvent catchUpEvent

The single catch-up event. Invokes catchUp(double) on the enclosing instance.

See Also:

CUPS.CatchUpEvent, catchUp(double)

Constructor Detail

CUPS

public CUPS(org.javades.jsimulation.r5.SimEventList eventList)

Creates a single-server CUPS queue with infinite buffer size given an event list.

The constructor registers a pre-update hook that sets the virtual time upon updates.

Parameters:

eventList - The event list to use.

See Also:

AbstractSimEntity.registerPreUpdateHook(java.util.function.DoubleConsumer), updateObtainedServiceTime(double)

Method Detail

getCopySimQueue

public CUPS<J,Q> getCopySimQueue()

Returns a new CUPS object on the same SimEventList.

Returns:

A new CUPS object on the same SimEventList.

See Also:

AbstractSimEntity.getEventList()

toStringDefault

public String toStringDefault()

Returns "CUPS".

Specified by:

toStringDefault in interface SimEntity

Overrides:

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

Returns:

"CUPS".

See Also:

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

getQoSClass

public final Class getQoSClass()

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

Returns:

The Java class used for QoS behavior, may be null.

getQoS

public final Object getQoS()

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

Returns:

The QoS value, may be null.

getJobsExecuting

protected final Set<J> getJobsExecuting()

Gets the jobs currently in execution.

Returns:

The jobs currently in execution (non-null).

getNumberOfJobsExecuting

protected final int getNumberOfJobsExecuting()

Gets the number of jobs in execution.

Returns:

The number of jobs in execution.

getMinimumObtainedServiceTime

protected final double getMinimumObtainedServiceTime()

Returns the minimum obtained service time (i.e., of all the jobs currently in execution).

Returns:

The minimum obtained service time, non-negative.

Throws:

IllegalStateException - If there are currently no jobs in execution (i.e., no jobs in the service area).

See Also:

AbstractSimQueue.hasJobsInServiceArea()

removeJobFromInternalAdministration

protected final void removeJobFromInternalAdministration(J job)

Removes the given job, if present, from the internal administration.

Does not remove the job from super-class structures.

Parameters:

job - The job to remove, non-null.

Throws:

IllegalArgumentException - If the job is null.

getTimeToCatchUp

protected final double getTimeToCatchUp()

Calculates the time until the next catch-up.

Returns:

The time until the next catch-up.

Throws:

IllegalStateException - If the current state of the queue does not allow a catch-up.

sanityInternalAdministration

protected final void sanityInternalAdministration()

Performs sanity checks on the internal administration.

Used for debugging. The checks, however, are quite expensive.

This method has no effect if all sanity checks pass.

Unless commented out due to code maturity and/or performance considerations, invocations are logged at level Level.FINER.

Throws:

IllegalStateException - If the internal administration is inconsistent.

resetEntitySubClass

protected final void resetEntitySubClass()

Calls super method and clears the internal administration.

Overrides:

resetEntitySubClass in class AbstractSimQueue<J extends SimJob,Q extends CUPS>

See Also:

SimEntity.resetEntity()

updateObtainedServiceTime

protected final void updateObtainedServiceTime(double newTime)

Updates the internal administration (i.c., obtained service times) for executing jobs in the service area.

This method is called as an pre-update hook, and not meant to be called from user code (in sub-classes). It is left protected for javadoc.

This method automatically performs "catch-ups".

Parameters:

newTime - The new time.

See Also:

AbstractSimQueue.hasJobsInServiceArea(), getJobsExecuting(), AbstractSimEntity.getLastUpdateTime(), AbstractSimEntity.registerPreUpdateHook(java.util.function.DoubleConsumer)

insertJobInQueueUponArrival

protected final void insertJobInQueueUponArrival(J job,
                                                 double time)

Does nothing, and makes that final.

Specified by:

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

Parameters:

job - The job that arrived.

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

See Also:

AbstractSimQueue.arrive(double, J)

rescheduleAfterArrival

protected final void rescheduleAfterArrival(J job,
                                            double time)

Starts the arrived job if server-access credits are available.

Specified by:

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

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.start(double, J)

removeJobFromQueueUponDrop

protected final void removeJobFromQueueUponDrop(J job,
                                                double time)

Throws IllegalStateException.

Specified by:

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

Parameters:

job - The job that is to be dropped.

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

Throws:

IllegalStateException - Always, as this SimQueue does not drop jobs.

See Also:

AbstractSimQueue.drop(J, double)

rescheduleAfterDrop

protected final void rescheduleAfterDrop(J job,
                                         double time)

Throws IllegalStateException.

Specified by:

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

Parameters:

job - The jobs that was dropped.

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

Throws:

IllegalStateException - Always, as this SimQueue does not drop jobs.

See Also:

AbstractSimQueue.drop(J, double)

removeJobFromQueueUponRevokation

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

Removes the jobs from the internal data structures.

Specified by:

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

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.revoke(double, J, boolean), removeJobFromInternalAdministration(J)

rescheduleAfterRevokation

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

Calls rescheduleDepartureEvent() and rescheduleCatchUpEvent().

Specified by:

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

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.revoke(double, J, boolean), rescheduleDepartureEvent(), rescheduleCatchUpEvent()

setServerAccessCreditsSubClass

protected final void setServerAccessCreditsSubClass()

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

Overrides:

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

See Also:

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

rescheduleForNewServerAccessCredits

protected final void rescheduleForNewServerAccessCredits(double time)

Starts jobs as long as there are server-access credits and jobs waiting.

Specified by:

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

Parameters:

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

See Also:

AbstractSimQueue.hasServerAcccessCredits(), AbstractSimQueue.hasJobsInWaitingArea(), AbstractSimQueue.start(double, J), AbstractSimQueue.getFirstJobInWaitingArea()

isStartArmed

public final boolean isStartArmed()

Returns true.

Returns:

True.

See Also:

SimQueueListener.notifyNewStartArmed(double, Q, boolean)

insertJobInQueueUponStart

protected final void insertJobInQueueUponStart(J job,
                                               double time)

Performs sanity checks and administers the job's initial obtained service time.

Specified by:

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

Parameters:

job - The job that starts.

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

See Also:

getServiceTimeForJob(J), obtainedServiceTimeMap

rescheduleAfterStart

protected final void rescheduleAfterStart(J job,
                                          double time)

Reschedules due to the start of a job, making it depart immediately if its requested service time is zero (or finite and time itself is infinite), or rescheduling through rescheduleDepartureEvent() and rescheduleCatchUpEvent() otherwise.

Specified by:

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

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(), rescheduleCatchUpEvent(), 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 CUPS>

Parameters:

job - The job, non-null.

Returns:

The result from the super method.

catchUp

protected final void catchUp(double time)

Calls AbstractSimEntity.update(double) followed by rescheduleDepartureEvent() and rescheduleCatchUpEvent().

Always invoked from (only) CUPS.CatchUpEvent.

Note that the actual catch-up is performed in updateObtainedServiceTime(double) through the pre-update hook. This method does however check that there are actually two groups of jobs in the service area with different obtained service times. Otherwise, we are illegally scheduled unless a recent update took place without rescheduling (e.g., a Queue Access Vacation). It also checks that after the AbstractSimEntity.update(double), the number of such groups has decreased by exactly one, again considering that we may have missed the catch-up due to a recent AbstractSimEntity.update(double).

For internal use but made protected for documentation purposes.

Parameters:

time - The time of the catch-up event (current time).

Throws:

IllegalStateException - If this method is invoked at an inappropriate moment, or the pre-update hook fails to perform the expected catch-up (in both cases, taking into consideration the possibility of missed updates).

See Also:

CUPS.CatchUpEvent, rescheduleDepartureEvent(), rescheduleCatchUpEvent()

removeJobFromQueueUponDeparture

protected final void removeJobFromQueueUponDeparture(J departingJob,
                                                     double time)

Calls removeJobFromQueueUponRevokation(J, double, boolean) for the departed job.

Specified by:

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

Parameters:

departingJob - The job that departs.

time - The departure (current) time.

See Also:

removeJobFromQueueUponRevokation(J, double, boolean)

rescheduleAfterDeparture

protected final void rescheduleAfterDeparture(J departedJob,
                                              double time)

Calls rescheduleDepartureEvent() and rescheduleCatchUpEvent().

Specified by:

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

Parameters:

departedJob - The departed job.

time - The departure (current) time.

See Also:

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

rescheduleDepartureEvent

protected final void rescheduleDepartureEvent()

Reschedules the single departure event for this queue.

Refuses to schedule departure events at positive or negative infinity.

See Also:

AbstractSimQueue.getDepartureEvents(), AbstractSimQueue.cancelDepartureEvent(org.javades.jqueues.r5.entity.jq.SimJQEvent.Departure<J, Q>), AbstractSimQueue.getJobsInServiceArea(), getServiceTimeForJob(J), getMinimumObtainedServiceTime(), AbstractSimQueue.scheduleDepartureEvent(double, J)

cancelCatchUpEvent

protected final void cancelCatchUpEvent()

Cancels a pending catch-up event (if scheduled).

The implementation simply removes the single catch-up event from the event list and from AbstractSimQueue.eventsScheduled.

See Also:

CUPS.CatchUpEvent, catchUpEvent, AbstractSimEntity.getEventList(), AbstractSimQueue.eventsScheduled

rescheduleCatchUpEvent

protected final void rescheduleCatchUpEvent()

Reschedules a catch-up event.

Refuses to schedule catch-up events at positive or negative infinity.

See Also:

cancelCatchUpEvent(), getTimeToCatchUp(), CUPS.CatchUpEvent, catchUpEvent