TipcMsgIncrRefCount

Name

TipcMsgIncrRefCount — increment the reference count of a message

Synopsis

T_BOOL TipcMsgIncrRefCount(msg) 
T_IPC_MSG msg; 

Arguments

msg — message to increment reference count for

Return Values

TRUE if the reference count was successfully incremented for the message, FALSE otherwise.

Diagnostics

If TipcMsgIncrRefCount fails, it returns FALSE and sets the global SmartSockets error number to one of:

Description

TipcMsgIncrRefCount increments the reference count of a message. The reference count property can be used to prevent a message from being destroyed. This is useful when using functions that always call TipcMsgDestroy, such as TipcConnMainLoop or TipcSrvMainLoop. For example, connection message-related callbacks are only given temporary access to a message, but sometimes these callbacks need to save the messages for later processing.

When a message is created or read from a connection, its reference count is initialized to 1. Each call to TipcMsgIncrRefCount increments the reference count. Each call to TipcMsgDestroy decrements the reference count. Once the reference count reaches 0, TipcMsgDestroy permanently destroys the message.

While TipcMsgClone can also be used to copy a message, if the message is not going to be modified then TipcMsgIncrRefCount can be used instead. TipcMsgIncrRefCount is much faster than TipcMsgClone because no memory allocation and copying is performed.

Caution

For each call to TipcMsgIncrRefCount there should be one call to TipcMsgDestroy to ensure proper destruction of a message when it is no longer needed, unless the message is passed to another function which takes responsibility for destroying the message (such as TipcSrvMsgInsert).

See Also

TipcMsgDestroy, TipcMsgGetRefCount

Examples

This example shows a connection process callback function which increments the reference count of a message and saves the messages for later processing:

void T_ENTRY example_process_cb(conn, data, arg) 
T_IPC_CONN conn; 
T_IPC_CONN_PROCESS_CB_DATA data; 
T_CB_ARG; 
{ 
 
  do_some_processing_now_on_msg(data->msg); 
 
  if (!TipcMsgIncrRefCount(data->msg)) { 
    return;  /* error */ 
  }  
 
  save_msg_for_later_processing(data->msg); 
 
} /* example_process_cb */ 

Once the later processing has been performed, the message can be destroyed by calling TipcMsgDestroy once for each call to TipcMsgIncrRefCount.