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);

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:

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 HCONDDEATH 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.

---

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

See also:

ham_attach(), ham_attach_self(), ham_condition_remove(), ham_connect(), ham_entity_handle()