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

 ---
 Author: József Gyürüsi
 Version: 22/155 16-CNL 113 512, Rev. B
 Date: 2010-09-24

 ---
 = EPTF CLL Semaphore, Function Description
 :author: József Gyürüsi
 :revnumber: 22/155 16-CNL 113 512, Rev. B
 :revdate: 2010-09-24
 :toc:

 == How to Read This Document

 This is the Function Description for the Semaphore of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). TitanSim 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 Semaphore feature of the TitanSim CLL.

 == Recommended Way of Reading

 The readers are supposed to get familiar with the concept and functionalities of TitanSim 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 Semaphore feature of the TitanSim CLL.

 The EPTF Semaphore feature makes it possible to implement blocking functions without using test port receive statements.

 There are some situations when a function shall block its execution until some event arrives. This event can be a message received on a test port or a scheduled timer event etc. The drawback of using a simple test port receive statement for waiting for a certain message is that, if some other message arrives on the same test port that cannot be extracted from the queue at the moment, then the message we are waiting for will never got extracted, because it is after the previous message in the event queue. The EPTF Semaphore feature provides a general solution for this problem by using timer events only.

 Also, by using EPTF Semaphores it is possible to synchronize events on the component.

 The Semaphores can be created on demand. They are identified by an integer ID. Using this ID the created semaphore can be unlocked later somewhere in the code. The function which blocks the execution until the semaphore is unlocked can be used to wait for the required event. When that event arrives, its handler function unlocks the semaphore and the waiting function will continue its operation.

 The states of the semaphore can be:

 * Locked (lock levels 1 and above)
 * Unlocked (lock level 0)

 The function that waits for the semaphore to be unlocked blocks its execution until the semaphore is unlocked. After creation the semaphore is in locked state (with lock level 1).

 The lock level of the semaphore can be increased and decreased one-by-one. This can be used for example to block execution until all answers for pending requests arrive.

 = Functional Interface

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

 == Naming Conventions

 All functions have the prefix `f_EPTF_Semaphore_`.

 == Public Functions

 === Initialization

 Before using the EPTF Semaphore functions the Semaphore feature should be initialized by calling the function:

 `f_EPTF_Semaphore_init_CT(selfName)`

 === Create a Semaphore

 To create a Semaphore, call the function

 `f_EPTF_Semaphore_new() return integer`

 The ID of the Semaphore is returned by this function.

 The created semaphore is in locked state (lock level is 1).

 === Delete a Semaphore

 To delete a Semaphore, call the function

 `f_EPTF_Semaphore_delete(id)`

 The Semaphore with the given ID is deleted. After that it cannot be locked.

 === Unlock a Semaphore

 To unlock a Semaphore call:

 `f_EPTF_Semaphore_unlock(id)`

 This function sets the locking state of the semaphore to unlocked (lock level 0). The function that waits for unlock will continue its execution after this function is called.

 === Lock a Semaphore

 To lock a Semaphore call:

 `f_EPTF_Semaphore_lock(id)`

 This function sets the locking state to locked (lock level 1 if it was unlocked, or does not change if it was already locked). The function that waits for unlock will block its execution.

 === Increase the Lock Level of a Semaphore

 To increase the level of a Semaphore call:

 `f_EPTF_Semaphore_increaseLock(id)`

 This function increases the lock level of the semaphore by 1. The function that waits for unlock will block its execution until the lock level decreases to zero.

 === Decrease the Lock Level of a Semaphore

 To decrease the lock level of a Semaphore call:

 `f_EPTF_Semaphore_decreaseLock(id)`

 This function decreases the lock level of the semaphore by 1. The function that waits for unlock will continue its execution when lock level is decreased to zero.

 === Wait for Unlocking the Semaphore

 To block the execution until the Semaphore is unlocked call the function:

 `f_EPTF_ Semaphore_waitForUnlock(id, maxWaitTime, autoDeleteSemaphore) return boolean`

 This function blocks the execution until the given Semaphore is unlocked. The maximum time to wait in seconds can also be specified. By default it is set to infinity (value `_-1.0_`). If the semaphore is not unlocked, the function will return `_true_` when the maximum waiting time passes, or never return if maximum waiting time is set to `_-1_`. If the semaphore is unlocked, the function will return `_false_`. The third parameter `autoDeleteSemaphore` can be used to enable/disable the deletion of the semaphore automatically before this function exits. By default the semaphore is deleted automatically.

 To be able to unlock the Semaphore when this function is called, the event handler of the unlocking event should be activated as default before calling this function, and that event handler shall unlock the semaphore when the requested event arrives.

 Note, that this function automatically deletes the Semaphore if the argument `autoDeleteSemaphore` is set to `_true_`.

 == Summary Table of All Public Functions for EPTF Semaphore

 See Summary of EPTF Semaphore functions in the table below:

 [width="100%",cols="40%,60%",options="header",]
 |=========================================================================================================================================================================================================================================================================================================================
 |Function name |Description
 |`f_EPTF_Semaphore_init_CT` |Initializes the `EPTF_Semaphore_CT` component
 |`f_EPTF_Semaphore_new` |Creates a new semaphore and returns its index.
 |`f_EPTF_Semaphore_delete` |Deletes the semaphore.
 |`f_EPTF_Semaphore_lock` |Locks the semaphore.
 |`f_EPTF_Semaphore_unlock` |Unlocks the semaphore.
 |`f_EPTF_Semaphore_increaseLock` |Increases the lock level by one.
 |`f_EPTF_Semaphore_decreaseLock` |Decreases the lock level by one.
 |`f_EPTF_Semaphore_waitForUnlock` |Blocks the execution until the semaphore is unlocked.
 |=========================================================================================================================================================================================================================================================================================================================

 = Terminology

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

 *Semaphore:* +
 The TTCN-3 way to solve blocking scenarios and perform synchronization

 = Abbreviations

 CLL:: Core Load 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. Part 1: Core Language

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

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

 [[_4]]
 [4] TitanSim CLL for TTCN-3 toolset with TITAN +
 http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]
	---
	Author: József Gyürüsi
	Version: 22/155 16-CNL 113 512, Rev. B
	Date: 2010-09-24

	---
	= EPTF CLL Semaphore, Function Description
	:author: József Gyürüsi
	:revnumber: 22/155 16-CNL 113 512, Rev. B
	:revdate: 2010-09-24
	:toc:

	== How to Read This Document

	This is the Function Description for the Semaphore of the Ericsson Performance Test Framework (TitanSim), Core Load Library (CLL). TitanSim 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 Semaphore feature of the TitanSim CLL.

	== Recommended Way of Reading

	The readers are supposed to get familiar with the concept and functionalities of TitanSim 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 Semaphore feature of the TitanSim CLL.

	The EPTF Semaphore feature makes it possible to implement blocking functions without using test port receive statements.

	There are some situations when a function shall block its execution until some event arrives. This event can be a message received on a test port or a scheduled timer event etc. The drawback of using a simple test port receive statement for waiting for a certain message is that, if some other message arrives on the same test port that cannot be extracted from the queue at the moment, then the message we are waiting for will never got extracted, because it is after the previous message in the event queue. The EPTF Semaphore feature provides a general solution for this problem by using timer events only.

	Also, by using EPTF Semaphores it is possible to synchronize events on the component.

	The Semaphores can be created on demand. They are identified by an integer ID. Using this ID the created semaphore can be unlocked later somewhere in the code. The function which blocks the execution until the semaphore is unlocked can be used to wait for the required event. When that event arrives, its handler function unlocks the semaphore and the waiting function will continue its operation.

	The states of the semaphore can be:

	* Locked (lock levels 1 and above)
	* Unlocked (lock level 0)

	The function that waits for the semaphore to be unlocked blocks its execution until the semaphore is unlocked. After creation the semaphore is in locked state (with lock level 1).

	The lock level of the semaphore can be increased and decreased one-by-one. This can be used for example to block execution until all answers for pending requests arrive.

	= Functional Interface

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

	== Naming Conventions

	All functions have the prefix `f_EPTF_Semaphore_`.

	== Public Functions

	=== Initialization

	Before using the EPTF Semaphore functions the Semaphore feature should be initialized by calling the function:

	`f_EPTF_Semaphore_init_CT(selfName)`

	=== Create a Semaphore

	To create a Semaphore, call the function

	`f_EPTF_Semaphore_new() return integer`

	The ID of the Semaphore is returned by this function.

	The created semaphore is in locked state (lock level is 1).

	=== Delete a Semaphore

	To delete a Semaphore, call the function

	`f_EPTF_Semaphore_delete(id)`

	The Semaphore with the given ID is deleted. After that it cannot be locked.

	=== Unlock a Semaphore

	To unlock a Semaphore call:

	`f_EPTF_Semaphore_unlock(id)`

	This function sets the locking state of the semaphore to unlocked (lock level 0). The function that waits for unlock will continue its execution after this function is called.

	=== Lock a Semaphore

	To lock a Semaphore call:

	`f_EPTF_Semaphore_lock(id)`

	This function sets the locking state to locked (lock level 1 if it was unlocked, or does not change if it was already locked). The function that waits for unlock will block its execution.

	=== Increase the Lock Level of a Semaphore

	To increase the level of a Semaphore call:

	`f_EPTF_Semaphore_increaseLock(id)`

	This function increases the lock level of the semaphore by 1. The function that waits for unlock will block its execution until the lock level decreases to zero.

	=== Decrease the Lock Level of a Semaphore

	To decrease the lock level of a Semaphore call:

	`f_EPTF_Semaphore_decreaseLock(id)`

	This function decreases the lock level of the semaphore by 1. The function that waits for unlock will continue its execution when lock level is decreased to zero.

	=== Wait for Unlocking the Semaphore

	To block the execution until the Semaphore is unlocked call the function:

	`f_EPTF_ Semaphore_waitForUnlock(id, maxWaitTime, autoDeleteSemaphore) return boolean`

	This function blocks the execution until the given Semaphore is unlocked. The maximum time to wait in seconds can also be specified. By default it is set to infinity (value `_-1.0_`). If the semaphore is not unlocked, the function will return `_true_` when the maximum waiting time passes, or never return if maximum waiting time is set to `_-1_`. If the semaphore is unlocked, the function will return `_false_`. The third parameter `autoDeleteSemaphore` can be used to enable/disable the deletion of the semaphore automatically before this function exits. By default the semaphore is deleted automatically.

	To be able to unlock the Semaphore when this function is called, the event handler of the unlocking event should be activated as default before calling this function, and that event handler shall unlock the semaphore when the requested event arrives.

	Note, that this function automatically deletes the Semaphore if the argument `autoDeleteSemaphore` is set to `_true_`.

	== Summary Table of All Public Functions for EPTF Semaphore

	See Summary of EPTF Semaphore functions in the table below:

	[width="100%",cols="40%,60%",options="header",]
	\|=========================================================================================================================================================================================================================================================================================================================
	\|Function name \|Description
	\|`f_EPTF_Semaphore_init_CT` \|Initializes the `EPTF_Semaphore_CT` component
	\|`f_EPTF_Semaphore_new` \|Creates a new semaphore and returns its index.
	\|`f_EPTF_Semaphore_delete` \|Deletes the semaphore.
	\|`f_EPTF_Semaphore_lock` \|Locks the semaphore.
	\|`f_EPTF_Semaphore_unlock` \|Unlocks the semaphore.
	\|`f_EPTF_Semaphore_increaseLock` \|Increases the lock level by one.
	\|`f_EPTF_Semaphore_decreaseLock` \|Decreases the lock level by one.
	\|`f_EPTF_Semaphore_waitForUnlock` \|Blocks the execution until the semaphore is unlocked.
	\|=========================================================================================================================================================================================================================================================================================================================

	= Terminology

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

	Semaphore: +
	The TTCN-3 way to solve blocking scenarios and perform synchronization

	= Abbreviations

	CLL:: Core Load 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. Part 1: Core Language

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

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

	[[_4]]
	[4] TitanSim CLL for TTCN-3 toolset with TITAN +
	http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]