doc/Scheduler/FS/EPTF CLL Scheduler, Function Description.adoc - titan/titan.Libraries.CLL - Git at Google

 ---
 Author: Zoltán Zsichla
 Version: 14/155 16-CNL 113 512, Rev. D
 Date: 2015-12-04

 ---
 = EPTF CLL Scheduler, Function Description
 :author: Zoltán Zsichla
 :revnumber: 14/155 16-CNL 113 512, Rev. D
 :revdate: 2015-12-04
 :toc:

 == How to Read This Document

 This is the Function Description for the Scheduler of the Ericsson Performance Test Framework (EPTF), Core Library (CLL). EPTF CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.

 == Scope

 This document is to specify the content and functionality of the Scheduler feature of the EPTF CLL.

 == Recommended Way of Reading

 The readers are supposed to get familiar with the concept and functionalities of EPTF CLL <<_3, [3]>>. They should get familiar with the list of acronyms and the glossary in the Terminology section.

 = General description

 This document specifies the Scheduler feature of the EPTF CLL.

 The EPTF Scheduler feature makes it possible to schedule events (actions) that should happen at a given time measured from the start of the component or relative to the schedule of the event. The Scheduler uses only two TTCN-3 timers to implement scheduling. These are the component clock – which is started at initialization – and the next event timer.

 To be able to use EPTF Scheduler, the user component should extend the `EPTF_Scheduler_CT` component.

 The EPTF Scheduler uses the EPTF Red Black Tree (see <<_5, [5]>>) to manage its database of events. To use the Scheduler, import the following modules:

 * `EPTF_CLL_Scheduler_Definitions`
 * `EPTF_CLL_RBTScheduler_Definitions`
 * `EPTF_CLL_RBTScheduler_Functions`

 The main altstep of the Scheduler is activated as default on initialization, and performs all necessary steps of handling actions automatically. A typical workflow using the functionality of the Scheduler is the following:

 * initializing the Scheduler
 * scheduling events, and specifying their handler callback function reference
 * handling events in their respective handler functions; handled events are automatically removed from the event queue
 * cancelling pending events by their event index if needed (for example during cleanup)

 = Functional Interface

 Apart from this description a cross-linked reference guide for the EPTF CLL Functions can be reached for on-line reading <<_4, [4]>>.

 == Naming Conventions

 All functions have the prefix `f_EPTF_Scheduler_`.

 Obsolete functions have the prefix `f_EPTF_SchedulerComp_`, for example `f_EPTF_SchedulerComp_refreshEventTimer`.

 == Public Functions

 === Initialization

 Before using the EPTF Scheduler functions the

 `f_EPTF_Scheduler_init_CT ()`

 function should be called. This initializes the EPTF Scheduler feature.

 A function with an obsolete name for the same functionality:

 `f_EPTF_SchedulerComp_InitScheduler()`

 === Scheduling an Action

 `f_EPTF_SchedulerComp_scheduleAction(pl_when, pl_actionHandler, pl_action, pl_eventIndex, pl_roundIt, pl_dteHandler)`

 This function can be used to register a new event to the event queue. The event is executed at the time when the component time reaches the value given in `pl_when`. The `pl_when` argument is rounded if `pl_roundIt` is true. At the execution time the hander given in `pl_actionHandler` is called with the parameters given in `pl_action`. The index of the event is returned in the parameter `pl_eventIndex`, and can be used, for example, to cancel the event later. Returns true on success, false on error.

 The argument `pl_dteHandler` defines the handler function that will be called when DTE happens during the execution of the action.

 Default: `_null_`, that is, no handler is called.

 === Cancelling an Action

 * `f_EPTF_SchedulerComp_CancelEvent(qidx)`
 +
 This function can be used to remove the event from the event queue. The function fails and returns false if the event at the specified index is not valid.

 === Action Handler

 The following private altstep is the main event handler of the Scheduler:

 * `as_EPTF_SchedulerComp_ActionHandler()`
 +
 The initialization function activates it as default, placing it in the main alt-loop of the component that extends the Scheduler.

 * `f_EPTF_SchedulerComp_performActions()`
 +
 This private function handles all actions that has a `when` parameter lower than or equal to the snapshot time taken from the component clock. It is called automatically by `as_EPTF_SchedulerComp_ActionHandler`

 === Load Measurement

 * `f_EPTF_Scheduler_enableLoadMeasurement(pl_enable)`
 +
 This function can be used to enable/disable load measurement for overload detection. The load is measured as the cumulative sum of lag of events during the load measurement period.

 * `f_EPTF_Scheduler_setLoadMeasurementPeriod(pl_loadMeasurementPeriod)`
 +
 This function can be used to set the load measurement time period (seconds).

 * `f_EPTF_Scheduler_setMaxLoadThreshold(pl_maxLoadThreshold)`
 +
 This function can be used to set the maximal load threshold When the load exceeds this value, the Scheduler actively controls the overload situation by scheduling events in the future only. If `maxLoadThreshold` is greater than `_1.0_`, there is no overload control.

 * `f_EPTF_Scheduler_getLoad()`
 +
 This function can be used to get the last measured load value. Its return value is between `_0.0_` (no load) and `_1.0_` (full load).

 * `f_EPTF_Scheduler_getLoadMeasurementInterval()`
 +
 This function can be used to get the last load measurement interval. If load measurement is not enabled, its return value is `_-1.0_`.

 == Miscellaneous Functions

 * `f_EPTF_SchedulerComp_refreshEventTimer()`
 +
 This private function sets the event timer to the time of the next scheduled action. It restarts the timer if necessary. This function is automatically called in `as_EPTF_SchedulerComp_ActionHandler`, `f_EPTF_SchedulerComp_scheduleAction` and `f_EPTF_SchedulerComp_CancelEvent`.

 * `f_EPTF_SchedulerComp_refreshSnapshotTime()`
 +
 This function reads the component clock and stores the time in `v_EPTF_snapshotTime` component variable. Proposed usage is to call it in the beginning of any altstep where `v_EPTF_snapshotTime` is used for example to schedule a new event.

 * `f_EPTF_SchedulerComp_refreshSnapshotTime()`
 +
 Returns the snapshot time, that is, the value of the component clock at the time when `f_EPTF_SchedulerComp_refreshSnapshotTime()` was called.

 * `f_EPTF_SchedlerComp_schedulerIsNotLate()`
 +
 This private function returns `_true_` if the head event within the event queue is scheduled later than the actual value of the component clock, otherwise returns `_false_`.

 * `f_EPTF_SchedulerComp_eventQueueIsNotEmpty()`
 +
 A private function to check whether the event queue is not empty. Returns true if the event queue is not empty, `_false_` otherwise.

 * `f_EPTF_SchedulerComp_eventQueueIsEmpty()`
 +
 A private function to check whether the event queue is empty. Returns true if the event queue is empty, `false` otherwise.

 * `f_EPTF_SchedulerComp_eventIsValid(pl_qidx)`
 +
 Function to check whether an event is valid within the event queue. Returns true if the event is valid. An event is invalid during it is executed. After executing the event, the event is automatically cancelled (that is, deleted).

 * `f_EPTF_SchedulerComp_eventIsInvalid(pl_qidx)`
 +
 Function to check whether an event is invalid within the event queue. Returns `_true_` if the event is invalid.

 == Summary Table of All Public Functions for EPTF Scheduler

 See Summary of Scheduler functions in the table below:

 [width="100%",cols="60%,40%",options="header",]
 |=====================================================================================
 |Function name |Description
 |`f_EPTF_Scheduler_init_CT` |initialization
 |`f_EPTF_SchedulerComp_scheduleAction` |schedule an event
 |`f_EPTF_SchedulerComp_CancelEvent` |cancel an existing event
 |`f_EPTF_SchedulerComp_refreshSnapshotTime` |refresh the snapshot time
 |`f_EPTF_SchedulerComp_snapshotTime` |returns the snapshot time
 |`f_EPTF_SchedulerComp_eventIsValid` |check if an event is valid
 |`f_EPTF_SchedulerComp_eventIsInvalid` |check if an event is invalid
 |`f_EPTF_Scheduler_enableLoadMeasurement` |enables/disables load measurement
 |`f_EPTF_Scheduler_setLoadMeasurementPeriod` |set the load measurement period
 |`f_EPTF_Scheduler_setMaxLoadThreshold` |set the maximal load value
 |`f_EPTF_Scheduler_getLoad` |get the last measured load value.
 |`f_EPTF_Scheduler_getLoadMeasurementInterval` |get the last load measurement interval
 |=====================================================================================

 = DTE Handling

 When the scheduler executes the action handler at the scheduled time and a dynamic test case error occurs, the scheduler does not stop the execution of the component but prints out a warning message about the error. It is also possible to specify an error handler function in `f_EPTF_SchedulerComp_scheduleAction`. That handler is called when the DTE occurs and receives the event parameters and the error string. When no handler is specified (which is the default) only the warning message is displayed about the error and the scheduler goes on to execute the next event.

 By default DTE handling is disabled.

 = Terminology

 *EPTF Core Library (CLL):* +
 It is that part of the TitanSim software that is totally project independent. (That is, which is not protocol-, or application-dependent). The EPTF CLL is to be supplied and supported by the TCC organization. Any EPTF CLL development is to be funded centrally by Ericsson.

 *Red Black Tree:* +
 The EPTF Red Black Tree feature is a self-balancing binary search tree. It can be used to store indexes into an associated array.

 = Abbreviations

 CLL:: Core Library

 EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

 TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

 TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

 = References

 [[_1]]
 [1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
 The Testing and Test Control Notation version 3. +
 http://www.etsi.org/deliver/etsi_es/201800_201899/20187301/03.02.01_60/es_20187301v030201p.pdf[Part 1: Core Language]

 [[_2]]
 [2] User Guide for TITAN TTCN-3 Test Executor

 [[_3]]
 [3] EPTF CLL for TTCN-3 toolset with TITAN, Function Specification

 [[_4]]
 [4] EPTF CLL for TTCN-3 toolset with TITAN +
 http://ttcn.ericsson.se/TCC_Releases/Libraries/EPTF_Core_Library_CNL113512/doc/apidoc/html/index.html[Reference Guide]

 [[_5]]
 [5] EPTF CLL Red Black Tree, Function Description
	---
	Author: Zoltán Zsichla
	Version: 14/155 16-CNL 113 512, Rev. D
	Date: 2015-12-04

	---
	= EPTF CLL Scheduler, Function Description
	:author: Zoltán Zsichla
	:revnumber: 14/155 16-CNL 113 512, Rev. D
	:revdate: 2015-12-04
	:toc:

	== How to Read This Document

	This is the Function Description for the Scheduler of the Ericsson Performance Test Framework (EPTF), Core Library (CLL). EPTF CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>.

	== Scope

	This document is to specify the content and functionality of the Scheduler feature of the EPTF CLL.

	== Recommended Way of Reading

	The readers are supposed to get familiar with the concept and functionalities of EPTF CLL <<_3, [3]>>. They should get familiar with the list of acronyms and the glossary in the Terminology section.

	= General description

	This document specifies the Scheduler feature of the EPTF CLL.

	The EPTF Scheduler feature makes it possible to schedule events (actions) that should happen at a given time measured from the start of the component or relative to the schedule of the event. The Scheduler uses only two TTCN-3 timers to implement scheduling. These are the component clock – which is started at initialization – and the next event timer.

	To be able to use EPTF Scheduler, the user component should extend the `EPTF_Scheduler_CT` component.

	The EPTF Scheduler uses the EPTF Red Black Tree (see <<_5, [5]>>) to manage its database of events. To use the Scheduler, import the following modules:

	* `EPTF_CLL_Scheduler_Definitions`
	* `EPTF_CLL_RBTScheduler_Definitions`
	* `EPTF_CLL_RBTScheduler_Functions`

	The main altstep of the Scheduler is activated as default on initialization, and performs all necessary steps of handling actions automatically. A typical workflow using the functionality of the Scheduler is the following:

	* initializing the Scheduler
	* scheduling events, and specifying their handler callback function reference
	* handling events in their respective handler functions; handled events are automatically removed from the event queue
	* cancelling pending events by their event index if needed (for example during cleanup)

	= Functional Interface

	Apart from this description a cross-linked reference guide for the EPTF CLL Functions can be reached for on-line reading <<_4, [4]>>.

	== Naming Conventions

	All functions have the prefix `f_EPTF_Scheduler_`.

	Obsolete functions have the prefix `f_EPTF_SchedulerComp_`, for example `f_EPTF_SchedulerComp_refreshEventTimer`.

	== Public Functions

	=== Initialization

	Before using the EPTF Scheduler functions the

	`f_EPTF_Scheduler_init_CT ()`

	function should be called. This initializes the EPTF Scheduler feature.

	A function with an obsolete name for the same functionality:

	`f_EPTF_SchedulerComp_InitScheduler()`

	=== Scheduling an Action

	`f_EPTF_SchedulerComp_scheduleAction(pl_when, pl_actionHandler, pl_action, pl_eventIndex, pl_roundIt, pl_dteHandler)`

	This function can be used to register a new event to the event queue. The event is executed at the time when the component time reaches the value given in `pl_when`. The `pl_when` argument is rounded if `pl_roundIt` is true. At the execution time the hander given in `pl_actionHandler` is called with the parameters given in `pl_action`. The index of the event is returned in the parameter `pl_eventIndex`, and can be used, for example, to cancel the event later. Returns true on success, false on error.

	The argument `pl_dteHandler` defines the handler function that will be called when DTE happens during the execution of the action.

	Default: `_null_`, that is, no handler is called.

	=== Cancelling an Action

	* `f_EPTF_SchedulerComp_CancelEvent(qidx)`
	+
	This function can be used to remove the event from the event queue. The function fails and returns false if the event at the specified index is not valid.

	=== Action Handler

	The following private altstep is the main event handler of the Scheduler:

	* `as_EPTF_SchedulerComp_ActionHandler()`
	+
	The initialization function activates it as default, placing it in the main alt-loop of the component that extends the Scheduler.

	* `f_EPTF_SchedulerComp_performActions()`
	+
	This private function handles all actions that has a `when` parameter lower than or equal to the snapshot time taken from the component clock. It is called automatically by `as_EPTF_SchedulerComp_ActionHandler`

	=== Load Measurement

	* `f_EPTF_Scheduler_enableLoadMeasurement(pl_enable)`
	+
	This function can be used to enable/disable load measurement for overload detection. The load is measured as the cumulative sum of lag of events during the load measurement period.

	* `f_EPTF_Scheduler_setLoadMeasurementPeriod(pl_loadMeasurementPeriod)`
	+
	This function can be used to set the load measurement time period (seconds).

	* `f_EPTF_Scheduler_setMaxLoadThreshold(pl_maxLoadThreshold)`
	+
	This function can be used to set the maximal load threshold When the load exceeds this value, the Scheduler actively controls the overload situation by scheduling events in the future only. If `maxLoadThreshold` is greater than `_1.0_`, there is no overload control.

	* `f_EPTF_Scheduler_getLoad()`
	+
	This function can be used to get the last measured load value. Its return value is between `_0.0_` (no load) and `_1.0_` (full load).

	* `f_EPTF_Scheduler_getLoadMeasurementInterval()`
	+
	This function can be used to get the last load measurement interval. If load measurement is not enabled, its return value is `_-1.0_`.

	== Miscellaneous Functions

	* `f_EPTF_SchedulerComp_refreshEventTimer()`
	+
	This private function sets the event timer to the time of the next scheduled action. It restarts the timer if necessary. This function is automatically called in `as_EPTF_SchedulerComp_ActionHandler`, `f_EPTF_SchedulerComp_scheduleAction` and `f_EPTF_SchedulerComp_CancelEvent`.

	* `f_EPTF_SchedulerComp_refreshSnapshotTime()`
	+
	This function reads the component clock and stores the time in `v_EPTF_snapshotTime` component variable. Proposed usage is to call it in the beginning of any altstep where `v_EPTF_snapshotTime` is used for example to schedule a new event.

	* `f_EPTF_SchedulerComp_refreshSnapshotTime()`
	+
	Returns the snapshot time, that is, the value of the component clock at the time when `f_EPTF_SchedulerComp_refreshSnapshotTime()` was called.

	* `f_EPTF_SchedlerComp_schedulerIsNotLate()`
	+
	This private function returns `_true_` if the head event within the event queue is scheduled later than the actual value of the component clock, otherwise returns `_false_`.

	* `f_EPTF_SchedulerComp_eventQueueIsNotEmpty()`
	+
	A private function to check whether the event queue is not empty. Returns true if the event queue is not empty, `_false_` otherwise.

	* `f_EPTF_SchedulerComp_eventQueueIsEmpty()`
	+
	A private function to check whether the event queue is empty. Returns true if the event queue is empty, `false` otherwise.

	* `f_EPTF_SchedulerComp_eventIsValid(pl_qidx)`
	+
	Function to check whether an event is valid within the event queue. Returns true if the event is valid. An event is invalid during it is executed. After executing the event, the event is automatically cancelled (that is, deleted).

	* `f_EPTF_SchedulerComp_eventIsInvalid(pl_qidx)`
	+
	Function to check whether an event is invalid within the event queue. Returns `_true_` if the event is invalid.

	== Summary Table of All Public Functions for EPTF Scheduler

	See Summary of Scheduler functions in the table below:

	[width="100%",cols="60%,40%",options="header",]
	\|=====================================================================================
	\|Function name \|Description
	\|`f_EPTF_Scheduler_init_CT` \|initialization
	\|`f_EPTF_SchedulerComp_scheduleAction` \|schedule an event
	\|`f_EPTF_SchedulerComp_CancelEvent` \|cancel an existing event
	\|`f_EPTF_SchedulerComp_refreshSnapshotTime` \|refresh the snapshot time
	\|`f_EPTF_SchedulerComp_snapshotTime` \|returns the snapshot time
	\|`f_EPTF_SchedulerComp_eventIsValid` \|check if an event is valid
	\|`f_EPTF_SchedulerComp_eventIsInvalid` \|check if an event is invalid
	\|`f_EPTF_Scheduler_enableLoadMeasurement` \|enables/disables load measurement
	\|`f_EPTF_Scheduler_setLoadMeasurementPeriod` \|set the load measurement period
	\|`f_EPTF_Scheduler_setMaxLoadThreshold` \|set the maximal load value
	\|`f_EPTF_Scheduler_getLoad` \|get the last measured load value.
	\|`f_EPTF_Scheduler_getLoadMeasurementInterval` \|get the last load measurement interval
	\|=====================================================================================

	= DTE Handling

	When the scheduler executes the action handler at the scheduled time and a dynamic test case error occurs, the scheduler does not stop the execution of the component but prints out a warning message about the error. It is also possible to specify an error handler function in `f_EPTF_SchedulerComp_scheduleAction`. That handler is called when the DTE occurs and receives the event parameters and the error string. When no handler is specified (which is the default) only the warning message is displayed about the error and the scheduler goes on to execute the next event.

	By default DTE handling is disabled.

	= Terminology

	EPTF Core Library (CLL): +
	It is that part of the TitanSim software that is totally project independent. (That is, which is not protocol-, or application-dependent). The EPTF CLL is to be supplied and supported by the TCC organization. Any EPTF CLL development is to be funded centrally by Ericsson.

	Red Black Tree: +
	The EPTF Red Black Tree feature is a self-balancing binary search tree. It can be used to store indexes into an associated array.

	= Abbreviations

	CLL:: Core Library

	EPTF:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

	TitanSim:: Ericsson Load Test Framework, formerly TITAN Load Test Framework

	TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

	= References

	[[_1]]
	[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
	The Testing and Test Control Notation version 3. +
	http://www.etsi.org/deliver/etsi_es/201800_201899/20187301/03.02.01_60/es_20187301v030201p.pdf[Part 1: Core Language]

	[[_2]]
	[2] User Guide for TITAN TTCN-3 Test Executor

	[[_3]]
	[3] EPTF CLL for TTCN-3 toolset with TITAN, Function Specification

	[[_4]]
	[4] EPTF CLL for TTCN-3 toolset with TITAN +
	http://ttcn.ericsson.se/TCC_Releases/Libraries/EPTF_Core_Library_CNL113512/doc/apidoc/html/index.html[Reference Guide]

	[[_5]]
	[5] EPTF CLL Red Black Tree, Function Description