:orphan:

.. index:: pair: group; API: Shared TA resources
.. _doxid-group__rcf__pch__rsrc:

API: Shared TA resources
========================

.. toctree::
	:hidden:

Overview
~~~~~~~~




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

	
	// typedefs

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_pch_rsrc_grab_callback<doxid-group__rcf__pch__rsrc_1ga04fb143adf0232a2ebda604fcab1fbc0>`)(const char *name);
	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*:ref:`rcf_pch_rsrc_release_callback<doxid-group__rcf__pch__rsrc_1ga69de4ac88908fe03eb7726fe09ddd0fc>`)(const char *name);

	// global variables

	const char* :ref:`te_lockdir<doxid-group__rcf__pch__rsrc_1ga70fde0302f343d22cc2b9b45852aa93b>`;

	// global functions

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`rcf_pch_rsrc_info<doxid-group__rcf__pch__rsrc_1gac4cf9d7196572f6d35b55bee8598378c>`(const char* name, :ref:`rcf_pch_rsrc_grab_callback<doxid-group__rcf__pch__rsrc_1ga04fb143adf0232a2ebda604fcab1fbc0>` grab, :ref:`rcf_pch_rsrc_release_callback<doxid-group__rcf__pch__rsrc_1ga69de4ac88908fe03eb7726fe09ddd0fc>` release);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :target:`rcf_pch_rsrc_grab_dummy<doxid-group__rcf__pch__rsrc_1ga8d28d2b9eec370d5c6a8f8d8ac4e5fd1>`(const char* name);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :target:`rcf_pch_rsrc_release_dummy<doxid-group__rcf__pch__rsrc_1ga83906207028f1cb56577868746db2356>`(const char* name);
	bool :ref:`rcf_pch_rsrc_accessible<doxid-group__rcf__pch__rsrc_1ga802fe7cb8653272418372df7e5dfd3c1>`(const char* fmt, ...);
	bool :ref:`rcf_pch_rsrc_accessible_may_share<doxid-group__rcf__pch__rsrc_1ga791399f7a2af930d4e0e0ddd71043e44>`(const char* fmt, ...);
	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` :ref:`rcf_pch_rsrc_check_locks<doxid-group__rcf__pch__rsrc_1ga674883f61d91e5fd65a716aff9741a2c>`(const char* rsrc_ptrn);
	void :ref:`rcf_pch_rsrc_init<doxid-group__rcf__pch__rsrc_1ga3dcc9910cf8dabb822c170aa5651c24f>`(void);

.. _details-group__rcf__pch__rsrc:

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



Typedefs
--------

.. index:: pair: typedef; rcf_pch_rsrc_grab_callback
.. _doxid-group__rcf__pch__rsrc_1ga04fb143adf0232a2ebda604fcab1fbc0:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_pch_rsrc_grab_callback)(const char *name)

These resources are resources provided by TA host (interfaces, services) which cannot be shared by several TAs and therefore should be locked/unlocked by particular TA dynamically.

When resource is grabbed/released by adding/deleting instance of /agent/rsrc object via Configurator.

Three strings are associated with each resource:

* resource instance name, used only for adding/deleting /agent/rsrc instances: e.g. r1 in /agent:A/rsrc:r1;

* resource name, which unique identifies the resource: "/agent:A/interface:eth0", "/agent/dnsserver" or "my_peripheral"; this name should be OID or string, without '/' symbols;

* resource generic name, which is used by rcfpch to discover callback for resource grabbing/releasing: e.g. /agent/interface.

The name and generic name may be the same unless there are many resources of the same class which grabbing/releasing is handled by the single callback (e.g. network interfaces).

To use some dynamically grabbed resource one should:

#. Provide to rcfpch information about grabbing/releasing callbacks for the resource. This may be done via explicit call of rcf_pch_rpcs_info during TA initialization or remote RCF or RCF RPC call.

#. Grab the resource from the test or during initialization adding /agent/rsrc instance via confapi or in cs.conf.

RCFPCH automatically creates the lock for the resource in TE_TMP directory. Name of the lock file containing TA PID is constructed as: ``${te_lockdir}/te_ta_lock_<converted name>``

"converted name" is resource name with '/' replaced by ''. te_lock_dir should be exported by the TA.

If lock of dead TA is found it is automatically removed. Callback for resource grabbing.



.. rubric:: Parameters:

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

	*
		- name

		- resource name



.. rubric:: Returns:

Status code

.. index:: pair: typedef; rcf_pch_rsrc_release_callback
.. _doxid-group__rcf__pch__rsrc_1ga69de4ac88908fe03eb7726fe09ddd0fc:

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

	typedef :ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` (*rcf_pch_rsrc_release_callback)(const char *name)

Callback for resource releasing.

Non-zero should be returned only if releasing is not allowed; in this case RCFPCH keeps the lock.



.. rubric:: Parameters:

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

	*
		- name

		- resource name



.. rubric:: Returns:

Status code

Global Variables
----------------

.. index:: pair: variable; te_lockdir
.. _doxid-group__rcf__pch__rsrc_1ga70fde0302f343d22cc2b9b45852aa93b:

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

	const char* te_lockdir

Directory for locks creation

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

.. index:: pair: function; rcf_pch_rsrc_info
.. _doxid-group__rcf__pch__rsrc_1gac4cf9d7196572f6d35b55bee8598378c:

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

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` rcf_pch_rsrc_info(const char* name, :ref:`rcf_pch_rsrc_grab_callback<doxid-group__rcf__pch__rsrc_1ga04fb143adf0232a2ebda604fcab1fbc0>` grab, :ref:`rcf_pch_rsrc_release_callback<doxid-group__rcf__pch__rsrc_1ga69de4ac88908fe03eb7726fe09ddd0fc>` release)

Specify callbacks for dynamically registerable resource.



.. rubric:: Parameters:

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

	*
		- name

		- resource generic name

	*
		- grab

		- grabbing callback

	*
		- release

		- releasing callback or NULL



.. rubric:: Returns:

Status code

.. index:: pair: function; rcf_pch_rsrc_accessible
.. _doxid-group__rcf__pch__rsrc_1ga802fe7cb8653272418372df7e5dfd3c1:

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

	bool rcf_pch_rsrc_accessible(const char* fmt, ...)

Check if the resource is accessible in exclusive mode.

The function should be called from TA main thread only.



.. rubric:: Parameters:

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

	*
		- fmt

		- format string for resource name



.. rubric:: Returns:

``true`` is the resource is accessible in exclusive mode

.. index:: pair: function; rcf_pch_rsrc_accessible_may_share
.. _doxid-group__rcf__pch__rsrc_1ga791399f7a2af930d4e0e0ddd71043e44:

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

	bool rcf_pch_rsrc_accessible_may_share(const char* fmt, ...)

Check if the resource is accessible in shared or exclusive mode.

The function should be called from TA main thread only.



.. rubric:: Parameters:

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

	*
		- fmt

		- format string for resource name



.. rubric:: Returns:

``true`` is the resource is accessible in shared or exclusive mode

.. index:: pair: function; rcf_pch_rsrc_check_locks
.. _doxid-group__rcf__pch__rsrc_1ga674883f61d91e5fd65a716aff9741a2c:

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

	:ref:`te_errno<doxid-te__errno_8h_1ac9fc14f28b70f4785037c1df70ebc2a5>` rcf_pch_rsrc_check_locks(const char* rsrc_ptrn)

Check if one of resources specified by glob pattern is locked by other agents.



.. rubric:: Parameters:

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

	*
		- rsrc_ptrn

		- Glob-style pattern of resourse name

	*
		- 0

		- No resources are locked.



.. rubric:: Returns:

Status code.

.. index:: pair: function; rcf_pch_rsrc_init
.. _doxid-group__rcf__pch__rsrc_1ga3dcc9910cf8dabb822c170aa5651c24f:

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

	void rcf_pch_rsrc_init(void)

Link resource configuration tree.