:orphan:

.. index:: pair: group; Stack of jumps
.. _doxid-group__ts__tapi__jmp:

Stack of jumps
==============

.. toctree::
	:hidden:

	struct_tapi_jmp_point.rst

Overview
~~~~~~~~

Definition of API to deal with thread-safe stack of jumps. :ref:`More...<details-group__ts__tapi__jmp>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// typedefs

	typedef struct :ref:`tapi_jmp_point<doxid-structtapi__jmp__point>` :ref:`tapi_jmp_point<doxid-group__ts__tapi__jmp_1ga292c2af49922d48992cecf982aae14b8>`;

	// structs

	struct :ref:`tapi_jmp_point<doxid-structtapi__jmp__point>`;

	// global functions

	:ref:`tapi_jmp_point<doxid-structtapi__jmp__point>`* :ref:`tapi_jmp_push<doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826>`(const char* file, unsigned int lineno);
	int :ref:`tapi_jmp_pop<doxid-group__ts__tapi__jmp_1ga296d5c13931e722f69a3a54aab2b0a59>`(const char* file, unsigned int lineno);
	int :ref:`tapi_jmp_do<doxid-group__ts__tapi__jmp_1gadb55ed57de3a6299504e994c59cdca19>`(int val, const char* file, unsigned int lineno);
	bool :ref:`tapi_jmp_stack_is_empty<doxid-group__ts__tapi__jmp_1gad3cec3b54900067061703c0932ae0789>`(void);

	// macros

	#define :ref:`TAPI_JMP_DO<doxid-group__ts__tapi__jmp_1gaa721e13439c47ddd6dbda1b877f94e0b>`(_val)
	#define :ref:`TAPI_JMP_POP<doxid-group__ts__tapi__jmp_1gab17c9ddff1456373869e77c2bca4ce4f>`
	#define :ref:`TAPI_ON_JMP<doxid-group__ts__tapi__jmp_1ga821eefae7af277b2505ee6b275588f24>`(x)
	#define :ref:`TAPI_ON_JMP_DO_SAFE_RC<doxid-group__ts__tapi__jmp_1ga25e594757955df7564357b39a69b6eb2>`
	#define :ref:`TAPI_ON_JMP_DO_SAFE_VOID<doxid-group__ts__tapi__jmp_1ga6a7104aaa44bdf3d15746f76a9e2633b>`

.. _details-group__ts__tapi__jmp:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Definition of API to deal with thread-safe stack of jumps.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Typedefs
--------

.. index:: pair: typedef; tapi_jmp_point
.. _doxid-group__ts__tapi__jmp_1ga292c2af49922d48992cecf982aae14b8:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	typedef struct :ref:`tapi_jmp_point<doxid-structtapi__jmp__point>` tapi_jmp_point

Jump point (stack context to jump to)

Global Functions
----------------

.. index:: pair: function; tapi_jmp_push
.. _doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	:ref:`tapi_jmp_point<doxid-structtapi__jmp__point>`* tapi_jmp_push(const char* file, unsigned int lineno)

Allocate and push long jump point in a stack (saved stack context for non-local goto).

The routine is thread-safe using per thread stacks of jump points.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- file

		- Name of the file where jump point is set

	*
		- lineno

		- Number of line in the file



.. rubric:: Returns:

Pointer to allocated long jump point.



.. rubric:: See also:

:ref:`tapi_jmp_do <doxid-group__ts__tapi__jmp_1gadb55ed57de3a6299504e994c59cdca19>`, :ref:`tapi_jmp_pop <doxid-group__ts__tapi__jmp_1ga296d5c13931e722f69a3a54aab2b0a59>`

.. index:: pair: function; tapi_jmp_pop
.. _doxid-group__ts__tapi__jmp_1ga296d5c13931e722f69a3a54aab2b0a59:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	int tapi_jmp_pop(const char* file, unsigned int lineno)

Remove jump point set using :ref:`tapi_jmp_push() <doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826>`.

The routine is thread-safe using per thread stacks of jump points.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- file

		- Name of the file where jump point is removed

	*
		- lineno

		- Number of line in the file

	*
		- TE_ENOENT

		- Stack of of jump points is empty



.. rubric:: Returns:

Status code



.. rubric:: See also:

:ref:`tapi_jmp_push <doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826>`, :ref:`tapi_jmp_do <doxid-group__ts__tapi__jmp_1gadb55ed57de3a6299504e994c59cdca19>`

.. index:: pair: function; tapi_jmp_do
.. _doxid-group__ts__tapi__jmp_1gadb55ed57de3a6299504e994c59cdca19:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	int tapi_jmp_do(int val, const char* file, unsigned int lineno)

Do non-local goto a stack context saved using :ref:`tapi_jmp_push() <doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826>`.

The routine is thread-safe using per thread stacks of jump points.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- val

		- Positive value to be returned by tapi_jmp_push (0 is mapped to TE_EOK)

	*
		- file

		- Name of the file where jump is done

	*
		- lineno

		- Number of line in the file

	*
		- TE_ENOENT

		- Stack of of jump points is empty



.. rubric:: Returns:

Status code



.. rubric:: See also:

:ref:`tapi_jmp_push <doxid-group__ts__tapi__jmp_1ga051f30cae55170f541f3b5d86882d826>`

.. index:: pair: function; tapi_jmp_stack_is_empty
.. _doxid-group__ts__tapi__jmp_1gad3cec3b54900067061703c0932ae0789:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	bool tapi_jmp_stack_is_empty(void)

Is stack of jumps empty?

c true Stack of jumps is empty c false Stack of jumps is not empty

Macros
------

.. index:: pair: define; TAPI_JMP_DO
.. _doxid-group__ts__tapi__jmp_1gaa721e13439c47ddd6dbda1b877f94e0b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JMP_DO(_val)

Macro for convinient use of :ref:`tapi_jmp_do() <doxid-group__ts__tapi__jmp_1gadb55ed57de3a6299504e994c59cdca19>`.

.. index:: pair: define; TAPI_JMP_POP
.. _doxid-group__ts__tapi__jmp_1gab17c9ddff1456373869e77c2bca4ce4f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_JMP_POP

Macro for convinient use of :ref:`tapi_jmp_pop() <doxid-group__ts__tapi__jmp_1ga296d5c13931e722f69a3a54aab2b0a59>`.

.. index:: pair: define; TAPI_ON_JMP
.. _doxid-group__ts__tapi__jmp_1ga821eefae7af277b2505ee6b275588f24:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_ON_JMP(x)

Create jump point with actions to be done in the case of jump.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- x

		- Actions to be done in the case of long jump (it is assumed that it does return, goto or exit)

.. index:: pair: define; TAPI_ON_JMP_DO_SAFE_RC
.. _doxid-group__ts__tapi__jmp_1ga25e594757955df7564357b39a69b6eb2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_ON_JMP_DO_SAFE_RC

The same as TAPI_ON_JMP_DO_SAFE_VOID.

Should be used at the beginning of functions that return int.

.. index:: pair: define; TAPI_ON_JMP_DO_SAFE_VOID
.. _doxid-group__ts__tapi__jmp_1ga6a7104aaa44bdf3d15746f76a9e2633b:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TAPI_ON_JMP_DO_SAFE_VOID

Set jump point in case some function raise an exception. We should capture it here and then decide whether to push it back to user with jump, or just return.

Should be used at the beginning of functions that return void.