API: Shared TA resources

Overview

// typedefs

typedef te_errno (*rcf_pch_rsrc_grab_callback)(const char *name);
typedef te_errno (*rcf_pch_rsrc_release_callback)(const char *name);

// global variables

const char* te_lockdir;

// global functions

te_errno rcf_pch_rsrc_info(const char* name, rcf_pch_rsrc_grab_callback grab, rcf_pch_rsrc_release_callback release);
te_errno rcf_pch_rsrc_grab_dummy(const char* name);
te_errno rcf_pch_rsrc_release_dummy(const char* name);
bool rcf_pch_rsrc_accessible(const char* fmt, ...);
bool rcf_pch_rsrc_accessible_may_share(const char* fmt, ...);
te_errno rcf_pch_rsrc_check_locks(const char* rsrc_ptrn);
void rcf_pch_rsrc_init(void);

Detailed Documentation

Typedefs

typedef te_errno (*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.

Parameters:

name	resource name

Returns:

Status code

typedef te_errno (*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.

Parameters:

name	resource name

Returns:

Status code

Global Variables

const char* te_lockdir

Directory for locks creation

Global Functions

te_errno rcf_pch_rsrc_info(const char* name, rcf_pch_rsrc_grab_callback grab, rcf_pch_rsrc_release_callback release)

Specify callbacks for dynamically registerable resource.

Parameters:

name	resource generic name
grab	grabbing callback
release	releasing callback or NULL

Returns:

Status code

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.

Parameters:

fmt	format string for resource name

Returns:

true is the resource is accessible in exclusive mode

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.

Parameters:

fmt	format string for resource name

Returns:

true is the resource is accessible in shared or exclusive mode

te_errno rcf_pch_rsrc_check_locks(const char* rsrc_ptrn)

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

Parameters:

rsrc_ptrn	Glob-style pattern of resourse name
0	No resources are locked.

Returns:

Status code.

void rcf_pch_rsrc_init(void)

Link resource configuration tree.