---

cm.h File Reference

Go to the source code of this file.

Data Structures
struct	_CMformat_list
Defines
#define	CM_FD   ATL_CHAR_CONS('C','S','F','D')
#define	CM_THIS_CONN_PORT   ATL_CHAR_CONS('C','S','C','P')
#define	CM_PEER_CONN_PORT   ATL_CHAR_CONS('C','S','P','P')
#define	CM_PEER_IP   ATL_CHAR_CONS('C','P','I','P')
#define	CM_PEER_LISTEN_PORT   ATL_CHAR_CONS('C','S','P','L')
#define	CM_PEER_HOSTNAME   ATL_CHAR_CONS('C','P','H','O')
#define	CM_IP_HOSTNAME   ATL_CHAR_CONS('C','I','P','H')
#define	CM_IP_ADDR   ATL_CHAR_CONS('C','I','P','A')
#define	CM_IP_PORT   ATL_CHAR_CONS('C','I','P','P')
#define	CM_UDP_PORT   ATL_CHAR_CONS('C','U','P','P')
#define	CM_TRANSPORT   ATL_CHAR_CONS('C','T','r','a')
#define	CM_ATM_ADDRESS   ATL_CHAR_CONS('C','A','T','A')
#define	CM_ATM_SELECTOR   ATL_CHAR_CONS('C','A','T','S')
#define	CM_ATM_BHLI   ATL_CHAR_CONS('C','A','T','B')
#define	CM_ATM_QOS_CLASS   ATL_CHAR_CONS('C','A','Q','C')
#define	CM_ATM_QOS_PCR   ATL_CHAR_CONS('C','A','Q','P')
#define	CM_ATM_QOS_SCR   ATL_CHAR_CONS('C','A','Q','S')
#define	CM_ATM_QOS_MBS   ATL_CHAR_CONS('C','A','Q','M')
#define	CM_ATM_FD   ATL_CHAR_CONS('C','A','F','D')
#define	CM_ATM_REMOTE_ADDRESS   ATL_CHAR_CONS('C','A','R','A')
#define	CM_ATM_REMOTE_SELECTOR   ATL_CHAR_CONS('C','A','R','S')
#define	CM_ATM_REMOTE_BHLI   ATL_CHAR_CONS('C','A','R','B')
#define	CM_ATM_CONN_VPI   ATL_CHAR_CONS('C','A','C','V')
#define	CM_ATM_CONN_VCI   ATL_CHAR_CONS('C','A','C','v')
#define	CM_MTP_HOSTNAME   ATL_CHAR_CONS('C','M','H','o')
#define	CM_MTP_ADDR   ATL_CHAR_CONS('C','M','A','d')
#define	CM_MTP_PORT   ATL_CHAR_CONS('C','M','P','o')
#define	CM_RECV_ERR   ATL_CHAR_CONS('C','R','R','E')
#define	CM_SEND_ERR   ATL_CHAR_CONS('C','R','S','E')
#define	CM_RECV_RATE   ATL_CHAR_CONS('C','R','R','R')
#define	CM_SEND_RATE   ATL_CHAR_CONS('C','R','S','R')
#define	CM_RTSEND_RATE   ATL_CHAR_CONS('C','R','R','T')
#define	CM_QOS   ATL_CHAR_CONS('C','Q','O','S')
#define	CM_WIN_INC   ATL_CHAR_CONS('C','R','W','I')
#define	CM_MAX_SEG   ATL_CHAR_CONS('C','R','M','S')
#define	CM_MARK   ATL_CHAR_CONS('C','R','M','a')
#define	CM_START_ADAPT   ATL_CHAR_CONS('C','R','S','A')
#define	CM_ADAPT_DEGREE   ATL_CHAR_CONS('C','R','A','D')
#define	CM_ADAPT_COND   ATL_CHAR_CONS('C','R','A','C')
Typedefs
typedef _CMformat_list	CMFormatRec
typedef CMFormatRec *	CMFormatList
typedef _CManager *	CManager
typedef _CMConnection *	CMConnection
typedef _CMFormat *	CMFormat
typedef _CMTaskHandle *	CMTaskHandle
typedef void(*	CMHandlerFunc )(CManager cm, CMConnection conn, void *message, void *client_data, attr_list attrs)
typedef void(*	CMPollFunc )(CManager cm, void *client_data)
typedef void(*	CMCloseHandlerFunc )(CManager cm, CMConnection conn, void *client_data)
typedef void(*	CMNonCMHandler )(CMConnection conn, int header)
Functions
CManager	CManager_create ()
void	CManager_close (CManager cm)
int	CMfork_comm_thread (CManager cm)
int	CMlisten (CManager cm)
int	CMlisten_specific (CManager cm, attr_list listen_info)
attr_list	CMget_contact_list (CManager cm)
int	CMcontact_self_check (CManager cm, attr_list attrs)
CMConnection	CMget_conn (CManager cm, attr_list contact_list)
CMConnection	CMinitiate_conn (CManager cm, attr_list contact_list)
void	CMConnection_close (CMConnection conn)
void	CMConnection_add_reference (CMConnection conn)
void	CMconn_register_close_handler (CMConnection conn, CMCloseHandlerFunc func, void *client_data)
CMFormat	CMregister_format (CManager cm, char *format_name, IOFieldList field_list, CMFormatList subformat_list)
CMFormat	CMlookup_format (CManager cm, IOFieldList field_list)
IOContext	CMget_user_type_context (CManager cm)
void	CMfree_user_type_context (CManager cm, IOContext context)
IOFormat	CMregister_user_format (CManager cm, IOContext context, char *format_name, IOFieldList field_list, CMFormatList subformat_list)
IOFormat	CMlookup_user_format (CManager cm, IOFieldList field_list)
IOFormat	CMget_IOformat_by_name (CManager cm, IOContext context, char *name)
IOFormat	CMget_format_IOcontext (CManager cm, IOContext context, void *buffer)
IOFormat *	CMget_subformats_IOcontext (CManager cm, IOContext context, void *buffer)
void	CMset_conversion_IOcontext (CManager cm, IOContext context, IOFormat format, IOFieldList field_list, int native_struct_size)
int	CMwrite (CMConnection conn, CMFormat format, void *data)
int	CMwrite_attr (CMConnection conn, CMFormat format, void *data, attr_list attrs)
void	CMregister_handler (CMFormat format, CMHandlerFunc handler, void *client_data)
void *	CMtake_buffer (CManager cm, void *data)
void	CMreturn_buffer (CManager cm, void *data)
void	CMregister_non_CM_message_handler (int header, CMNonCMHandler handler)
void	CMadd_poll (CManager cm, CMPollFunc func, void *client_data)
CMTaskHandle	CMadd_periodic_task (CManager cm, int period_sec, int period_usec, CMPollFunc func, void *client_data)
CMTaskHandle	CMadd_delayed_task (CManager cm, int secs, int usecs, CMPollFunc func, void *client_data)
void	CMremove_task (CMTaskHandle handle)
void	CMadd_shutdown_task (CManager cm, CMPollFunc func, void *client_data)
CMTaskHandle	CMadd_periodic (CManager cm, long period, CMPollFunc func, void *client_data)
void	CMremove_periodic (CMTaskHandle handle)
void	CMsleep (CManager cm, int secs)
void	CMusleep (CManager cm, int usecs)
void	CMpoll_network (CManager cm)
void	CMrun_network (CManager cm)
int	CMCondition_get (CManager cm, CMConnection dep)
int	CMCondition_wait (CManager cm, int condition)
void	CMCondition_signal (CManager cm, int condition)
void	CMCondition_set_client_data (CManager cm, int condition, void *client_data)
void *	CMCondition_get_client_data (CManager cm, int condition)
int	CMCondition_has_signaled (CManager cm, int condition)
int	CMCondition_has_failed (CManager cm, int condition)
void *	CMrealloc (void *ptr, int size)
void *	CMmalloc (int size)
void	CMfree (void *ptr)
long	CMprobe_latency (CMConnection conn, int msg_size, attr_list attrs)
long	CMprobe_bandwidth (CMConnection conn, int size, attr_list attrs)

---

Detailed Description

---

Typedef Documentation

typedef struct _CMformat_list CMFormatRec

A structure to hold Format Name / Field List associations. This is used to associate names with field lists. Together these define a structure that can be composed into larger structures.

typedef CMFormatRec* CMFormatList

A list of CMFormatRec structures. In it's use in CM, a CMFormatList represents the transitive closure of substructures that compose a larger structure. The name/field list entry for each particular format should appear before it is used (in the field lists of later entries). This implies that the first entry has only fields which have atomic data types.

typedef struct _CManager* CManager

CManager is the root of control flow and message handling in a CM program. CManager is an opaque handle.

typedef struct _CMConnection* CMConnection

CMConnection is a handle to a communications link. CManager is an opaque handle.

typedef struct _CMFormat* CMFormat

CMFormat is a handle to a registered native format. CMFormat is an opaque handle. It is the return value from CMregister_format() and is used both to identify data for writing (in CMwrite() and CMwrite_attr() and to register handlers for incoming data (with CMregister_handler()).

typedef struct _CMTaskHandle* CMTaskHandle

CMTaskHandle is a handle to a delayed or periodic task.

typedef void(* CMHandlerFunc)(CManager cm, CMConnection conn, void *message, void *client_data, attr_list attrs)

The prototype for a CM data handling function. CM allows application-routines matching this prototype to be registered as data handlers. Parameters: cm  The CManager with which this handler was registered. conn  The CMConnection upon which the message arrived. message  A pointer to the incoming data, cast to void*. The real data is formatted to match the fields of with which the format was registered. client_data  This value is the same client_data value that was supplied in the CMregister_handler() call. It is not interpreted by CM, but instead can be used to maintain some application context. attrs  The attributes (set of name/value pairs) that this message was delivered with. These are determined by the transport and may include those specified in CMwrite_attr() when the data was written.

typedef void(* CMPollFunc)(CManager cm, void *client_data)

The prototype for a CM polling handler (and others). Functions matching of this prototype can be registered with CMadd_poll(), CMadd_periodic_task(), CMadd_delayed_task() and CMadd_shutdown_task(). Parameters: cm  The CManager with which this handler was registered. client_data  This value is the same client_data value that was supplied in the CMadd_poll() call. It is not interpreted by CM, but instead can be used to maintain some application context.

typedef void(* CMCloseHandlerFunc)(CManager cm, CMConnection conn, void *client_data)

The prototype for a CM connection close handler. Functions matching of this prototype can be registered with CMregister_close_handler(). Parameters: cm  The CManager with which this handler was registered. conn  The CMConnection which is being closed. client_data  This value is the same client_data value that was supplied in the CMregister_close_handler() call. It is not interpreted by CM, but instead can be used to maintain some application context.

typedef void(* CMNonCMHandler)(CMConnection conn, int header)

The prototype for a non-CM message handler. Functions matching of this prototype can be registered with CMregister_non_CM_message_handler(). Parameters: conn  The CMConnection on which the message is available. header  The first 4 bytes of the message, encoded as an integer.

---

Function Documentation

CManager CManager_create (    )

create a CManager. CManager is the root of control flow and message handling in a CM program.

void CManager_close (  CManager    cm )

close a CManager the close operation shuts down all connections and causes the termination of any network handling thread. Parameters: cm  The CManager to be shut down.

int CMfork_comm_thread (  CManager    cm )

fork a thread to handle the network input operations of a CM. Parameters: cm  The CManager whose input should be handled by a new thread. Returns: 0 if a communications manager thread cannot be forked 1 success Warning: Only one thread should be handling input for a CM. If this call is used then no other thread should call CMpoll_network() or CMrun_network(). If this call is to be used (or indeed if any threading is to be used), one of the gen_thread init routines should be called before the call to CManager_create(). Otherwise bad things will happen.

int CMlisten (  CManager    cm )

Tell CM to listen for incoming network connections. Parameters: cm  The CManager which should listen. Returns: the number of transports which successfully initiated connection listen operations (by reporting contact attributes). Note: CMlisten() is identical to calling CMlisten_specific() with a NULL value for the listen_info parameter. The listening transports will add their contact information to the list returned by CMget_contact_list().

int CMlisten_specific (  CManager    cm, attr_list    listen_info )

Tell CM to listen for incoming network connections with specific characteristics. Parameters: cm  The CManager which should listen. listen_info  An attribute list to be passed to the transport-provided listen operations of all currently-loaded transports. Returns: the number of transports which successfully initiated connection listen operations (by reporting contact attributes). Note: The listen_info value is interpreted by each individual transport. Currently implemented transports that use this include: the sockets tranport which uses the CM_IP_PORT attribute to control which port it listens on. If this attribute is not present it listens on any available port. the rudp tranport which uses the CM_UDP_PORT attribute to control which port it listens on. If this attribute is not present it listens on any available port. the atm tranport which uses the CM_ATM_SELECTOR and CM_ATM_BHLI attribute to control listens. These attributes must be present.

attr_list CMget_contact_list (  CManager    cm )

get the contact information for this CM. This call returns the set of attributes that define the contact information for the network transports that have performed listen operations. Parameters: cm  the CManager for which to return contact information. Returns: the contact list.

int CMcontact_self_check (  CManager    cm, attr_list    attrs )

check to see if this is contact information for this CM. Since attribute lists are generally opaque, it is not necessarily obvious when you have a set of contract attributes that is actually your own contact list. This call is designed to answer that question. Parameters: cm  The CManager whose contact information should be compared. attrs  The contact list to compare. Returns: 1 if for some loaded transport the attrs list matches the contact information in the cm. 0 othewise.

CMConnection CMget_conn (  CManager    cm, attr_list    contact_list )

acquire a (possibly existing) connection to another CM process. Parameters: cm  The CManager in which to make the connection. contact_list  The attribute list specifying contact information for the remote CM. Returns: A CMConnection value, or NULL in the event of failure. CMget_conn() attempts to determine if the contact attribute match any existing connection (Using the transport connection_eq() method). If a connection matches, that connection's reference count is incremented and its value is returned. If no connection matches, a CMinitiate_conn() is performed using the contact list and its result value is returned.

CMConnection CMinitiate_conn (  CManager    cm, attr_list    contact_list )

initiate connection to another CM process. Parameters: cm  The CManager in which to make the connection. contact_list  The attribute list specifying contact information for the remote CM. Returns: A CMConnection value, or NULL in the event of failure. CMinitiate_conn() will attempt to initiate a connection using each of the currently loaded transports. It will return the first that succeeds, or NULL if none succeed. Note: If the contact list contains a CM_TRANSPORT attribute with a string value, CMinitiate_conn() will attempt to load that transport, then if that succeeds will attempt to initiate a connection using only that transport.

void CMConnection_close (  CMConnection    conn )

shut down a connection. Parameters: conn  the CMConnection to shut down. CMConnection_close decrements the reference count of a connection. If the resulting reference count is zero, then the connection is shut down. All resources associated with the connection are free'd, the close handler is called and the CMConnection structure itself is free'd. Warning: CMConnection values should not be used after CMConnection_close()

void CMConnection_add_reference (  CMConnection    conn )

manually increment the reference count of a connection. Parameters: conn  the CMConnection whose count should be incremented. Note: Used if some mechanism other than CMget_conn() is used to "share" connection in multiple contexts so that it is closed only when all users have closed it.

void CMconn_register_close_handler (  CMConnection    conn, CMCloseHandlerFunc    func, void *    client_data )

register a function to be called when a connection is closed. Parameters: conn  the connection with which the function is associated. func  the function to be called when the connection closes. client_data  An uninterpreted value that is passed to the function when it is called. Note: There can be only one close handler per connection. Multiple registrations overwrite each other.

CMFormat CMregister_format (  CManager    cm, char *    format_name, IOFieldList    field_list, CMFormatList    subformat_list )

register a format with CM. Parameters: cm  The CManager in which to register the format. format_name  The textual name to associate with the structure format. field_list  The PBIO field list which describes the structure. subformat_list  A list of name/field_list pairs that specify the representation of any nested structures in the message. If the message field types are simple pre-defined PBIO types, subformat_list can be NULL. Otherwise it should contain the transitive closure of all data types necessary to specify the message representation. The list is terminated with a {NULL, NULL}<\tt> value. Registering a format is a precursor to sending a message or registering a handler for incoming messages.

CMFormat CMlookup_format (  CManager    cm, IOFieldList    field_list )

lookup the CMFormat associated with a particular IOFieldList Parameters: cm  The CManager in which the format was registered. field_list  The field list which was used in the registration. CMLookup_format() addresses a specific problem particular to libraries. CMwrite() requires a CMFormat value that results from a CMregister_format() call. Efficiency would dictate that the CMregister_format() be performed once and the CMFormat value used repeatedly for multiple writes. However, libraries which want to avoid the use of static variables, or which wish to support multiple CM values per process have no convenient way to store the CMFormat values for reuse. CMlookup_format() exploits the fact that field_lists are often constants with fixed addresses (I.E. their memory is not reused for other field lists later in the application). This call quickly looks up the CMFormat value in a CM by searching for a matching field_list address. Warning: You should *not* use this convenience routine if you cannot guarantee that all field lists used to register formats have a unique address.

int CMwrite (  CMConnection    conn, CMFormat    format, void *    data )

send a message on a connection. Parameters: conn  The CMConnection upon which to send the message. format  The CMFormat value returned by CMregister_format(). data  The unencoded message, cast to a void* value. Returns: 1 if the write was successful. 0 if the write did not complete successfully. Note: CMwrite() is equivalent to CMwrite_attr() with a NULL value passed for the attrs parameter.

int CMwrite_attr (  CMConnection    conn, CMFormat    format, void *    data, attr_list    attrs )

send a message on a connection with particular attributes. Parameters: conn  The CMConnection upon which to send the message. format  The CMFormat value returned by CMregister_format(). data  The unencoded message, cast to a void* value. attrs  The set of name/value attributes with which to write the data. Returns: 1 if the write was successful. 0 if the write did not complete successfully. Note: The values in the attrs parameter serve two purposes. First, they may be interpreted by CM or the CM transport layers on either the writing or reading sides to customize event delivery. Second, they are made available (perhaps with additional transport-specific attributes) to the read-side handler in the attrs argument to the CMHandlerFunc that handles the message. CMwrite_attr() with a NULL value for the attrs parameter is equivalent to CMwrite().

void CMregister_handler (  CMFormat    format, CMHandlerFunc    handler, void *    client_data )

register a function to be called when message matching a particular format arrives. Parameters: format  The CMFormat value returned by CMregister_format() handler  The function to be called to handle the message. client_data  An uninterpreted value that is passed to the function when it is called.

void* CMtake_buffer (  CManager    cm, void *    data )

assume control over a incoming buffer of data. This call is designed to be used inside a CMHandlerFunc. Normally data buffers are recycled and CM only guarantees that the data delivered to a CMHandlerFunc will be valid for the duration of the call. In that circumstance, a handler that wanted to preserve the data for longer than it's own duration (to pass it to a thread or enter it into some other data structure for example) would have to copy the data. To avoid that inefficiency, CMtake_buffer() allows the handler to take control of the buffer holding its incoming data. The buffer will then not be recycled until it is returned to CM with CMreturn_buffer(). Parameters: cm  The CManager in which the handler was called. data  The base address of the data (I.E. the message parameter to the CMHandlerFunc). Returns: NULL on error, otherwise returns the data parameter.

void CMreturn_buffer (  CManager    cm, void *    data )

return a buffer of incoming data. This call recycles a data buffer that the application has taken control of through CMtake_buffer(). Parameters: cm  The CManager in which the handler was called. data  The base address of the data (I.E. same value that was passed to CMtake_buffer().

void CMregister_non_CM_message_handler (  int    header, CMNonCMHandler    handler )

register a handler for raw (non-CM) messages. CM, like may other message layers, embeds a unique value in the first 4 bytes of the incoming message to identify it as a CM message. CM actually has several sets of identifying 4-byte values that it recognizes as CM-internal messages. This interface can be used to add to that set to include non-CM messages (such as IIOP, HTTP, etc.). Parameters: header  The 4 bytes that identify (encoded as an integer) that identify the messages to be handled. handler  The handler to be called when messages with this header arrive. Note: Registration is not CManager-specific, but apply to all CManagers in the address space (ugly). Warning: Don't do this at home kids! This API is not complete enough to actually implement something like IIOP externally, but it's the thought that counts.

void CMadd_poll (  CManager    cm, CMPollFunc    func, void *    client_data )

add a task (function) to be executed occasionally. Parameters: cm  The CManager to which the task is added. func  The function to be called occasionally. client_data  An uninterpreted value that is passed to the function when it is called. CM poll functions are called after each round of message delivery. I.E. once per call to CMpoll_network() if that function is used.

CMTaskHandle CMadd_periodic_task (  CManager    cm, int    period_sec, int    period_usec, CMPollFunc    func, void *    client_data )

add a task (function) to be executed with a specified periodicity. Parameters: cm  The CManager to which the task is added. period_sec  The number of whole seconds of the period. period_usec  The number of additional microseconds of the period. func  The function to be called periodically. client_data  An uninterpreted value that is passed to the function when it is called. Returns: a CMTaskHandle which can be used to remove the task. Note: CM does not guarantee a particular periodicity, it merely applies its best efforts. I.E. It will not block wait in select() past the timeout period for the next task. However handlers may run long and I/O may intervene to delay the task execution. The task will be executed when the first opportunity arises after it is scheduled. After execution is complete, the next execution will be scheduled based upon the actual execution time of the current invocation (not when it was scheduled to be executed).

CMTaskHandle CMadd_delayed_task (  CManager    cm, int    secs, int    usecs, CMPollFunc    func, void *    client_data )

add a task (function) to be executed at a later time. Parameters: cm  The CManager to which the task is added. secs  The number of whole seconds to delay the task. usecs  The number of additional microseconds to delay the task. func  The function to be called after the delay. client_data  An uninterpreted value that is passed to the function when it is called. Returns: a CMTaskHandle which can be used to remove the task (only before it executes). Note: CM does not guarantee a particular delay, it merely applies its best efforts. I.E. It will not block wait in select() past the timeout period for the next task. However handlers may run long and I/O may intervene to delay the task execution. The task will be executed when the first opportunity arises after it is scheduled.

void CMremove_task (  CMTaskHandle    handle )

remove a registered periodic or delayed task. Parameters: handle  The handle to the task to remove.

void CMadd_shutdown_task (  CManager    cm, CMPollFunc    func, void *    client_data )

add a task (function) to be called when the CM is shut down. Parameters: cm  The CManager to which a shutdown task is added. func  The function to be called upon shutdown. client_data  An uninterpreted value that is passed to the function when it is called. Multiple shutdown tasks can be added to the same CM and they are called in the order registered. There is currently no API for removing them.

CMTaskHandle CMadd_periodic (  CManager    cm, long    period, CMPollFunc    func, void *    client_data )

add a task to be executed with a particular periodicity. Parameters: cm  The CManager which should execute the task. period  The period of the task in microseconds. func  The function to be called. client_data  An uninterpreted value that is passed to the function when it is called. Returns: a CMTaskHandle which can be used to remove the task. Deprecated: Use CMadd_periodic_task().

void CMremove_periodic (  CMTaskHandle    handle )

remove a registered periodic task. Parameters: handle  The handle to the task to remove. Deprecated: Use CMremove_task()

void CMsleep (  CManager    cm, int    secs )

sleep for a given number of seconds. Unlike system sleep() calls, CMsleep() will continue to handle network messages during the sleep time. In particular, if CMsleep is called by the network handler thread or in a single threaded program, then it will enter a network handling loop until the time has elapsed. If called by other than the network handler thread in a multithread application, then it will suspend on a thread condition wait until the time has elapsed. Parameters: cm  The CManager upon which to sleep. secs  The number of seconds for which to sleep.

void CMusleep (  CManager    cm, int    usecs )

sleep for a given number of microseconds. Unlike system sleep() calls, CMusleep() will continue to handle network messages during the sleep time. In particular, if CMusleep is called by the network handler thread or in a single threaded program, then it will enter a network handling loop until the time has elapsed. If called by other than the network handler thread in a multithread application, then it will suspend on a thread condition wait until the time has elapsed. Parameters: cm  The CManager upon which to sleep. usecs  The number of microseconds for which to sleep.

void CMpoll_network (  CManager    cm )

handle one round of network events Parameters: cm  The CManager for which to handle events. CMpoll_network()} is one of the basic network event handling calls in CM. A CM network event is a basic communications occurrence, such as a connection request or message arrival. The routine CMpoll_network() essentially polls the network and handles some pending messages before returning. Note: Not all pending messages will be handled, but generally one message will be handled for each connection upon which input is pending.

void CMrun_network (  CManager    cm )

handle network events until shutdown. Parameters: cm  The CManager for which to handle events. CMrun_network()} is one of the basic network event handling calls in CM. A CM network event is a basic communications occurrence, such as a connection request or message arrival. The routine CMrun_network() essentially handles network events until the CManager is shutdown.

int CMCondition_get (  CManager    cm, CMConnection    dep )

allocate a new CM condition value. Parameters: cm  the CManager value in which to allocate the condition. dep  the CMConnection value upon which the condition depends. Returns: an integer value representing a CM condition. Note: CM condition values are used to cause a thread or program to wait for a particular situation, usually for a message response to arrive. In this case the condition value is acquired before sending the request message, integer condition value is sent as part of the request and returned in the response. The response handler then does a CMCondition_signal() as part of its operation. The dep CMConnection value is used in error handling. In particular, if that connection dies or is closed, the condition will be marked as failed and the corresponding CMCondition_wait() will return. Thus if the situation in which the condition is used relies upon the continued operation of a connection (such as waiting for a response), then that connection should be specified as the dep parameter in this call. If there is no such reliance, dep can be NULL.

int CMCondition_wait (  CManager    cm, int    condition )

wait for a CM condition value. Parameters: cm  the CManager value in which the condition was allocated. condition  the condition upon which to wait. Returns: 1 if the condition was signalled normally. 0 if the CMConnection specified as dep in the CMCondition_get() call was closed. Note: CM condition values are used to cause a thread or program to wait for a particular situation, usually for a message response to arrive. CMCondition_wait() is useful because it does the "right thing" in both single-threaded and multi-threaded applications. In single-threaded applications it enters a network-handling loop until the condition has been signaled. In applications with a network handler thread, it checks to see if it is being executed by that handler thread. If it is *not*, then it does a thread condition wait to suspect the thread. If it is being executed by the network handler thread, then it also enters a network-handling loop until the condition has been signaled. Warning: The condition value is considered 'free'd upon return from CMCondition_wait() and should not be used in any subsequent call (including calls to CMCondition_get_client_data(), etc.).

void CMCondition_signal (  CManager    cm, int    condition )

signal a CM condition value. Parameters: cm  the CManager value in which the condition was allocated. condition  the condition to be signaled. Note: CM condition values are used to cause a thread or program to wait for a particular situation, usually for a message response to arrive. CMCondition_signal() notifies CM that the situation needed to satisfy a particualr condition variable has occurred and any waiting thread should awaken.

void CMCondition_set_client_data (  CManager    cm, int    condition, void *    client_data )

set the client_data associated with a condition value. Parameters: cm  the CManager value in which the condition is allocated. condition  the condition with which the client_data should be associated. client_data  the value to be associated with the condition. Note: The client_data value is not interpreted by CM, but instead provides a mechanism through which information can be conveyed between the requesting thread and response handler. In a typical usage, the requesting site sets the client_data to the address of storage for a return value. The response handler then uses CMCondition_get_client_data() to access that address and store the return value in the appropriate location. Warning: Calls to CMCondition_set_client_data() should occur between the call to CMCondition_alloc() and CMCondition_wait(). The condition value is considered 'free'd upon return from CMCondition_wait() and should not be used in any subsequent call. To avoid possible race conditions, calls to CMCondition_set_client_data() should also occur before the CMwrite of the request to ensure that the response doesn't arrive before the client data is set.

void* CMCondition_get_client_data (  CManager    cm, int    condition )

get the client_data associated with a condition value. Parameters: cm  the CManager value in which the condition is allocated. condition  the condition to query for client_data. Returns: the client_data value associated with the condition. Note: The client_data value is not interpreted by CM, but instead provides a mechanism through which information can be conveyed between the requesting thread and response handler. In a typical usage, the requesting site sets the client_data to the address of storage for a return value. The response handler then uses CMCondition_get_client_data() to access that address and store the return value in the appropriate location. Warning: Calls to CMCondition_get_client_data() should generally occur in the response handler (as opposed to after CMCondition_wait()). The condition value is considered 'free'd upon return from CMCondition_wait() and should not be used in any subsequent call.

int CMCondition_has_signaled (  CManager    cm, int    condition )

test whether or not a particular condition has been signaled. Parameters: cm  the CManager value in which the condition is allocated. condition  the condition to test. Returns: boolean value representing whether or not the condition has been signaled. This call essentially provides a mechanism of examining the state of a condition without blocking on CMCondition_wait(). Warning: This call should not be used on a condition after a CMCondition_wait() has been performed.

int CMCondition_has_failed (  CManager    cm, int    condition )

test whether or not a particular condition has failed. Parameters: cm  the CManager value in which the condition is allocated. condition  the condition to test. Returns: boolean value representing whether or not the condition has failed (I.E. its dependent connection has been closed.) This call essentially provides a mechanism of examining the state of a condition without blocking on CMCondition_wait(). Warning: This call should not be used on a condition after a CMCondition_wait() has been performed.

void* CMrealloc (  void *    ptr, int    size )

reallocate a chunk of memory Parameters: ptr  the memory to reallocate size  the new size Returns: a pointer to the new block

void* CMmalloc (  int    size )

allocate a chunk of memory Parameters: size  the requested size Returns: a pointer to the new block

void CMfree (  void *    ptr )

free a chunk of memory Parameters: ptr  the memory to free

---