The HAM API library maintains only one connection to the HAM. The library itself is thread-safe, and multiple connections (from different threads) or the same thread are multiplexed on the same single connection to a HAM. The library maintains reference counts.
Here are the basic connect functions:
/* Basic connect functions return success (0) or failure (-1, with errno set) */ int ham_connect(unsigned flags); int ham_connect_nd(int nd, unsigned flags); int ham_connect_node(const char *nodename, unsigned flags); int ham_disconnect(unsigned flags); int ham_disconnect_nd(int nd, unsigned flags); int ham_disconnect_node(const char *nodename, unsigned flags);
These functions are used to open or close connections to a HAM. The first call to ham_connect*() will open the fd, while subsequent calls will increment the reference count.
Similarly, ham_disconnect() will decrement the count until zero; the call that makes the count zero will close the fd. The functions return -1 on error, and 0 on success. Similarly ham_disconnect*() will decrement the reference count until zero, with the call that makes the count zero closing the fd. The functions return -1 on error with errno set, and 0 on success.
In a multithreaded situation, there will exist only one open connection to a given HAM at any given time, even if multiple threads were to perform ham_connect*()/ham_disconnect*() calls.
The ham_*_nd() and ham_*_node() versions of the calls are used to open a connection to a remote HAM across QNET. The nd that is passed to the function is the node identifier that refers to the remote host at the instant the call is made. Since node identifiers are transient values, it is essential that the node identifier is obtained just prior to the call. The other option is to use the fully qualified node name (FQNN) of the host and to pass this as the nodename parameter. An nd of ND_LOCAL_NODE (a constant defined in sys/netmgr.h) or a nodename of NULL (or the empty string) are equivalent, and refer to the current node. (This is also the same as calling ham_connect() or ham_disconnect() directly).
Calls to ham_connect(), ham_connect_nd(), and ham_connect_node() can be freely mixed, as long as the number of connect calls equals the number of disconnect calls for each connection to a specific (local or remote) HAM before the connection (fd) is closed.