Next: , Up: Exchanging Data Packets in a Multithreaded Program   [Contents][Index]


6.4.1 Registering Interaction Sides

Before exchanging data packets, the application program must register sides that will take part in the interaction. A registered side is referred to by a side handle.

Data type: qsmm_side_t

This is a type for a side handle. It is a pointer, so variables of this type can have the NULL value. The function qsmm_side_create allocates a new side handle. The function qsmm_side_destroy frees an existing side handle. After allocating a side handle, it can be passed to API functions that take an argument of type qsmm_side_t until the handle is freed.

To register and unregister an interaction side, the following functions can be used.

Function: int qsmm_side_create (const char *name, qsmm_side_t *side_p)

This function registers interaction side name and stores a newly allocated side handle in *side_p. If side_p is NULL, then the function will have no effect. The value of name is dumped in the trace log of data packets exchange between sides. If side_p is not NULL, then name must not be NULL. The function creates a copy of name and stores it in the internal structure.

The function returns a non-negative value on success or a negative error code on failure in registering a side. Currently, the following error codes can be returned.

QSMM_SIDE_ERR_PTHREAD

A POSIX threads API error.

QSMM_SIDE_ERR_NOMEM

There was not enough memory to register a side.

Function: void qsmm_side_destroy (qsmm_side_t side)

This function unregisters an interaction side specified by handle side. After unregistering the side, its handle must not be used. If side is NULL, then the function will have no effect.

To get the name of an interaction side specified by its handle, the following function can be used.

Function: const char * qsmm_get_side_name (qsmm_side_t side)

This function returns the name of a side specified when creating the side. The returned value is never NULL.


Next: , Up: Exchanging Data Packets in a Multithreaded Program   [Contents][Index]