ham_attach_self()

Attach an application as a self-attached entity

Synopsis:

#include <ha/ham.h>

ham_entity_t *ham_attach_self(
                 const char *ename, 
                 _Uint64t hp,
                 int hpdl, 
                 int hpdh, 
                 unsigned flags );

Library:

libham

Description:

You use the ham_attach_self() call to attach an application as a self-attached entity to the HAM. A self-attached entity is a process that chooses to send heartbeats to the HAM, which will then monitor the process for failure. Self-attached entities can, on their own, decide at exactly what point in their lifespan they want to be monitored, what conditions they want acted upon, and when they want to stop the monitoring.

Note that self-attached entities can be any processes, not just those in session 1 (unlike the requirement for the ham_attach() call).

Once an entity has been attached, you can add conditions and actions to it.

---

Since the ham_attach*() functions open a connection to the HAM, for convenience they also perform the initial ham_connect() call. So any client that makes a ham_attach_self() call doesn't need to call ham_connect() or ham_disconnect() before and after the call to ham_attach_self().

---

The arguments are as follows:

ename

The name of the entity. This must be unique across the whole context of the HAM. Self-attached entities can also specify an interval at which they'll send heartbeats to the HAM. The heartbeat can be used to detect unresponsive processes that aren't dead.

hp

The heartbeat interval in nanoseconds. The lowest permissible heartbeat interval is defined in the constant HAMHBEATMIN (see <ha/ham.h>). Use 0 if no heartbeat is desired.

---

Note that here you're specifying the heartbeat interval — the client must still call the ham_heartbeat() function to actually transmit the heartbeat.

---

hpdl

The number of permissible missed heartbeats before CONDHBEATMISSEDLOW is triggered. The value of hpdl must be ≤ hpdh.

hpdh

As for hpdl, but for CONDHBEATMISSEDHIGH. The value of hpdh must be ≥ hpdl.

flags

There are no flags defined at this time.

Returns:

A valid handle to an entity on success; otherwise, NULL (errno is set).

Errors:

EBADF

Couldn't connect to the HAM.

EEXIST

The name provided for the entity already exists.

EINVAL

The name given in ename is invalid (e.g. it contains the “/” character) or is NULL.

ENAMETOOLONG

The name given (in aname) is too long, i.e. it exceeds _POSIX_PATH_MAX (defined in <limits.h>). Note that the combined length of an entity/condition/action name is also limited by _POSIX_PATH_MAX.

ENOMEM

Not enough memory to create a new handle.

In addition to the above errors, the HAM returns any error it encounters while servicing the request to add a new entity to its context.

Classification:

QNX Neutrino

See also:

ham_attach(), ham_condition(), ham_connect(), ham_detach(), ham_detach_self(), ham_disconnect(), ham_heartbeat()

procmgr_daemon() in the QNX Neutrino Library Reference