doc/NQueue/UG/EPTF CLL NQueue, User Guide.adoc - titan/titan.Libraries.CLL - Git at Google

 ---
 Author: Gábor Tatárka
 Version: 31/198 17-CNL 113 512, Rev. A
 Date: 2011-06-07

 ---
 = EPTF CLL NQueue, User Guide
 :author: Gábor Tatárka
 :revnumber: 31/198 17-CNL 113 512, Rev. A
 :revdate: 2011-06-07
 :toc:

 == About This Document

 === How to Read This Document

 This is the User Guide for the `NQueue` 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]>>. This document should be read together with the Function Description of the `NQueue` feature <<_5, [5]>>. For more information on the TitanSim CLL, consult the Users Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.

 == System Requirements

 In order to use the `NQueue` feature the system requirements listed in TitanSim CLL User Guide <<_4, [4]>> should be fulfilled.

 = `NQueue`

 == Overview

 The EPTF CLL `NQueue` component is a fundamental component providing a general implementation of linked lists. It can be used, among others, for dynamic memory allocation in a load test environment for the TTCN-3 language and sorting records of complex data structures without actually moving the data.

 Furthermore, the `NQueue` feature makes it possible to assign a given state to a given item in a list of data by moving the item with the same index in the queue to the chain representing that state. The state of an item (chain ID) can then be requested from the queue with the item index, and changed by moving the item to another chain. It also makes it possible to iterate through the items of the associated data with the same state by iterating through the chain from head to tail or tail to head. Items can also be reordered within chains.

 See an example of `NQueue` and associated data list in the figure below:

 image:images/NQueue_assoc_data_list_2.png[alt]

 An example can be seen on Figure above, with two chains representing two states of the associated data. Iterating head to tail through chain 0 of the queue would result in item indexes 0, 1, 7, 6, 5.

 [[desc_files_this_feature]]
 == Description of Files in This Feature

 The EPTF CLL `NQueue` feature includes the following files:

 * __EPTF_CLL_NQueue_Definitions.ttcn__ - type definitions
 * __EPTF_CLL_NQueue_ExternalFunctions.cc__ - implementation of the feature
 * __EPTF_CLL_NQueue_Functions.ttcn__ - function declarations specifying the API that can be used from within TTCN-3


 [[desc_req_files_other_features]]
 == Description of Required Files From Other Features

 The `NQueue` feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. To use the `NQueue` the user has to obtain the respective files from the following features:

 * `Base`
 * `Common`

 == Installation

 Since EPTF CLL `NQueue` is used as a part of the TTCN-3 test environment this requires TTCN-3 Test Executor to be installed before any operation of these functions. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.

 If not otherwise noted in the respective sections, the following are needed to use EPTF CLL NQueue:

 * Copy the files listed in Sections <<desc_files_this_feature, Description of Files in This Feature>> and <<desc_req_files_other_features, Description of Required Files From Other Features>> to the directory of the test suite or create symbolic links to them.
 * Import the `NQueue` demo or write your own application using `NQueue`.
 * Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, [2]>>.
 * Edit the configuration file according to your needs, see section <<config, Configuration>>.

 [[config]]
 == Configuration

 The executable test program behavior is determined via the run-time configuration file. This is a simple text file, which contains various sections. The usual suffix of configuration files is _.cfg_. For further information on the configuration file see <<_2, [2]>>.

 The `NQueue` feature does not define TTCN-3 module parameters.

 = Error Messages

 NOTE: Besides the below described error messages, error messages shown in <<_2, [2]>> or those of other used features or products may also appear.

 The `NQueue` feature may log one of the following error messages (and stop execution):

 `*<function-name>: invalid queue <n>, number of queues: <m>*`

 `*<function-name>: invalid queue <n>, queue has been deleted.*`

 `*<function-name>: invalid chain <n>, number of chains in queue: <m>*`

 `*<function-name>: invalid item <n>, number of items in queue: <m>*`

 = Examples

 The "demo" directory of the deliverable contains the following examples:

 * __EPTF_NQueue_Demo.cfg__
 * __EPTF_NQueue_Demo.prj__
 * __EPTF_NQueue_Demo.ttcn__

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

 *NQueue:* +
 It is a data type consisting of an arbitrary number of chains and an arbitrary number of items. Items in the queue are identified by their index, which has a continuous range and is thus useful for creating associated data structures by indexing a list of data with the item index.

 *Chain:* +
 It is a group of items in the queue. Each item belongs to a chain and can be moved to another chain. A chain is represented as a doubly linked list and can be iterated forward (head to tail) or backward (tail to head). A chain can, for example, be thought of as the state of its items (e.g. free/busy).

 = 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, User Guide

 [[_5]]
 [5] EPTF CLL NQueue, Function Description

 [[_6]]
 [6] TitanSim CLL for TTCN-3 toolset with TITAN +
 http://ttcn.ericsson.se/products/libraries.shtml[Reference Guide]
	---
	Author: Gábor Tatárka
	Version: 31/198 17-CNL 113 512, Rev. A
	Date: 2011-06-07

	---
	= EPTF CLL NQueue, User Guide
	:author: Gábor Tatárka
	:revnumber: 31/198 17-CNL 113 512, Rev. A
	:revdate: 2011-06-07
	:toc:

	== About This Document

	=== How to Read This Document

	This is the User Guide for the `NQueue` 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]>>. This document should be read together with the Function Description of the `NQueue` feature <<_5, [5]>>. For more information on the TitanSim CLL, consult the Users Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.

	== System Requirements

	In order to use the `NQueue` feature the system requirements listed in TitanSim CLL User Guide <<_4, [4]>> should be fulfilled.

	= `NQueue`

	== Overview

	The EPTF CLL `NQueue` component is a fundamental component providing a general implementation of linked lists. It can be used, among others, for dynamic memory allocation in a load test environment for the TTCN-3 language and sorting records of complex data structures without actually moving the data.

	Furthermore, the `NQueue` feature makes it possible to assign a given state to a given item in a list of data by moving the item with the same index in the queue to the chain representing that state. The state of an item (chain ID) can then be requested from the queue with the item index, and changed by moving the item to another chain. It also makes it possible to iterate through the items of the associated data with the same state by iterating through the chain from head to tail or tail to head. Items can also be reordered within chains.

	See an example of `NQueue` and associated data list in the figure below:

	image:images/NQueue_assoc_data_list_2.png[alt]

	An example can be seen on Figure above, with two chains representing two states of the associated data. Iterating head to tail through chain 0 of the queue would result in item indexes 0, 1, 7, 6, 5.

	[[desc_files_this_feature]]
	== Description of Files in This Feature

	The EPTF CLL `NQueue` feature includes the following files:

	* __EPTF_CLL_NQueue_Definitions.ttcn__ - type definitions
	* __EPTF_CLL_NQueue_ExternalFunctions.cc__ - implementation of the feature
	* __EPTF_CLL_NQueue_Functions.ttcn__ - function declarations specifying the API that can be used from within TTCN-3


	[[desc_req_files_other_features]]
	== Description of Required Files From Other Features

	The `NQueue` feature is part of the TitanSim EPTF Core Load Library (CLL). It relies on several features of the CLL. To use the `NQueue` the user has to obtain the respective files from the following features:

	* `Base`
	* `Common`

	== Installation

	Since EPTF CLL `NQueue` is used as a part of the TTCN-3 test environment this requires TTCN-3 Test Executor to be installed before any operation of these functions. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.

	If not otherwise noted in the respective sections, the following are needed to use EPTF CLL NQueue:

	* Copy the files listed in Sections <<desc_files_this_feature, Description of Files in This Feature>> and <<desc_req_files_other_features, Description of Required Files From Other Features>> to the directory of the test suite or create symbolic links to them.
	* Import the `NQueue` demo or write your own application using `NQueue`.
	* Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, [2]>>.
	* Edit the configuration file according to your needs, see section <<config, Configuration>>.

	[[config]]
	== Configuration

	The executable test program behavior is determined via the run-time configuration file. This is a simple text file, which contains various sections. The usual suffix of configuration files is _.cfg_. For further information on the configuration file see <<_2, [2]>>.

	The `NQueue` feature does not define TTCN-3 module parameters.

	= Error Messages

	NOTE: Besides the below described error messages, error messages shown in <<_2, [2]>> or those of other used features or products may also appear.

	The `NQueue` feature may log one of the following error messages (and stop execution):

	`<function-name>: invalid queue <n>, number of queues: <m>`

	`<function-name>: invalid queue <n>, queue has been deleted.`

	`<function-name>: invalid chain <n>, number of chains in queue: <m>`

	`<function-name>: invalid item <n>, number of items in queue: <m>`

	= Examples

	The "demo" directory of the deliverable contains the following examples:

	* __EPTF_NQueue_Demo.cfg__
	* __EPTF_NQueue_Demo.prj__
	* __EPTF_NQueue_Demo.ttcn__

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

	NQueue: +
	It is a data type consisting of an arbitrary number of chains and an arbitrary number of items. Items in the queue are identified by their index, which has a continuous range and is thus useful for creating associated data structures by indexing a list of data with the item index.

	Chain: +
	It is a group of items in the queue. Each item belongs to a chain and can be moved to another chain. A chain is represented as a doubly linked list and can be iterated forward (head to tail) or backward (tail to head). A chain can, for example, be thought of as the state of its items (e.g. free/busy).

	= 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, User Guide

	[[_5]]
	[5] EPTF CLL NQueue, Function Description

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