ham_condition()

Set up a condition to be triggered when a certain event occurs

Synopsis:

#include <ha/ham.h>

ham_condition_t *ham_condition(ham_entity_t *ehdl,
                               int type, 
                               const char *cname,
                               unsigned flags);

Arguments:

ehdl: The HAM entity handle.
type: The type parameter indicates the situations of the condition and entity. See below.
cname: The name of the condition.
flags: The flags indicating how the condition should be performed. See below.

Library:

libham

Description:

You call this function to set up a condition that will be triggered when a significant event occurs.

Each entity can be associated with several different conditions, and associated with each of these conditions is a set of actions that will be performed in FIFO sequence when the condition is true. If an entity has multiple conditions that are true simultaneously, with different sets of actions associated with each condition, then all the actions associated with each condition are performed, in sequence.

This mechanism lets you combine actions together into sets and choose to remove/control them as a single “group” instead of as individual items.

The ehdl argument is an entity handle obtained either:

from a ham_attach*() call or a ham_entity*() call
or:
by calling ham_entity_handle*() with an existing entity name. Since conditions are associated with entities, the entity handle (ehdl) must be available before you can add conditions.

Since conditions are associated with entities, the entity handle (ehdl) must be available before you can add conditions.

You can specify any of the following for type:

CONDABNORMALDEATH: The entity has died an abnormal death. This condition is triggered whenever an entity dies by a mechanism that results in the generation of a core file (see dumper in the Utilities Reference for details).
CONDANY: This condition type matches any condition type. It can be used to associate the same actions with one of many conditions.
CONDATTACH: An entity for which a placeholder was previously created (someone has subscribed to events relating to this entity), has joined the system. This is also the start of the monitoring of the entity by a HAM.
CONDDEATH: The entity died.
An entity's death is detected for all processes in session 1, for processes that terminate abnormally (typically due to the delivery of a signal), and for processes that are attached as self-attached entities.
CONDDETACH: The entity detached from the HAM.
CONDHBEATMISSEDLOW: The entity missed a heartbeat specified as “low” severity.
CONDHBEATMISSEDHIGH: The entity missed a heartbeat specified as “high” severity.
CONDRESTART: The entity was restarted.

The cname argument is the condition name. It must be unique across all conditions in the given entity.

When a condition is triggered, all actions defined in all conditions of the given type are executed. When an entity dies, a condition of type CONDDEATH is triggered, and all actions in all conditions that match this type are executed.

Currently the following flags are defined:

HCONDINDEPENDENT: Indicates that the actions associated with this condition are to be performed in a separate thread. When a condition is triggered, actions within it are performed in FIFO order. For multiple conditions that are simultaneously triggered, the conditions are serviced in an arbitrary order. By setting this flag, you're marking the condition as independent — all actions associated with it are executed in a separate thread, independent of actions in other conditions.
HCONDNOWAIT: Indicates that the condition can't contain any “waitfor” actions. Waitfor actions are normally slow and may contain significant delays. This will delay the execution of subsequent actions in the list. Specifying HCONDNOWAIT guarantees there will be no delays once the condition is triggered.
HREARMAFTERRESTART: Indicates that the condition is to be automatically re-armed after the entity that it belongs to is restarted. Be default, this flag is disabled — conditions automatically get removed across restarts of the entity. Note that if the entity that the condition belongs to gets removed, this condition will also be removed, regardless of the state of this flag.

Note: You must call the ham_connect() function before the first call to ham_condition() in a process. If a process calls ham_connect() and then calls fork(), the child process must call ham_connect() again before it can successfully call ham_condition() in order to add conditions.

Returns:

A valid handle to a condition in the given entity; otherwise, NULL (and errno is set).

Errors:

EBADF: Couldn't connect to the HAM.
EEXIST: The name provided for the condition already exists.
EINVAL: The handle, type, or name given is invalid (e.g., it contains the “/” character) or is NULL.
The connection to the HAM is invalid. This happens when the process that opened the connection (using ham_connect()) and the process that's calling ham_condition() aren't the same.
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 this request.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes