Callbacks

SmartSockets makes use of callbacks to allow you visibility into the internal processing. A callback is a mechanism that allows you to monitor a type of event. The callback is associated with a certain object or with all objects of a certain type. Callbacks associated with all objects of a given type are called global callbacks. When the event occurs, the specified callback function is called to notify you that the event happened.

An example of this type of function is a variable change callback. Such a callback could be used so that the application can monitor the changing of a variable’s value, and do other processing required to support the requirements. Callbacks belong to a callback list, which is an ordered set of all the callbacks created for a given event type and object.

There is a generic, abstract type of callbacks called T_CB. This type has a set of properties such as function, priority, argument, and so on. Because it is an abstract type, it is not directly accessible. You can create these abstracts with functions such as TipcSrvSubjectCbCreate. You can manipulate them with the TutCb* access functions such as TutCbSetPriority. The Tipc* functions are documented in the TIBCO SmartSockets Application Programming Interface reference, and the Tut* functions are documented in the TIBCO SmartSockets Utilities reference.

The specific types of callbacks that are provided vary depending on the process, but all SmartSockets callbacks have certain common characteristics. Each process (RTserver, RTmon, and so on.) provides a set of functions to deal with callbacks specific to that process. Typically, there is a TprocessTypeCbCreate function and a TprocessTypeCbLookup function that can be used to create and look up callbacks. Examples of these include TipcConnDefaultCbCreate, TipcConnDefaultCbLookup, TipcSrvSubjectCbCreate, and TipcSrvSubjectCbLookup. All other operations performed on callbacks are done using TutCb* functions.

Callback functions always return void.

Callbacks have a priority associated with them that allows you to specify order. The priority specifies the order in which callbacks are called. Higher priority callbacks are called before lower priority ones. If two callbacks have the same priority, their relative calling order is undetermined.

Callbacks are uniquely identified by function and argument within a given list. This means you cannot register two callbacks which use the same callback function and callback argument within the same list of callbacks.

All callback function definitions and prototypes must be declared with the macro T_ENTRY for cross-platform portability.

All callback functions take exactly three arguments. The first is the object to which the callback is related, the second points to a callback data structure, and the third is a user-specified argument that is specified when the callback is created. Depending on the callback, the first argument may not be used. Check the documentation for the callback being used. The generic callback function is defined as:

typedef void (*T_CB_FUNC) (T_CB_OBJ ptr, T_CB_DATA data, T_CB_ARG arg);

There is usually a callback data structure specific to the type of callback being used, but not always. There is a generic callback data structure definition provided that is defined as:

typedef struct T_CB_DATA_STRUCT { T_CB cb; } T_CB_DATA_STRUCT, *T_CB_DATA;

This data structure contains just a pointer to the callback that is being called. This is useful for managing the callback during execution of the callback function.

Any changes to a callback list, such as deletions, additions, or priority changes, are applied to the list after the current callback list has been processed. Changes to the list occur on the next traversal of the list. Here are two examples:

Adding new callbacks: If a callback with priority 100 is being executed, and in that callback function, a new callback with priority 120 is created and added to the same list, that new callback is not called during the processing of the list.

Changing the priority of callbacks: If a callback of priority 100 is executing, and it changes the priority of an existing priority 50 callback (in the same list) to priority 120, this callback is not processed during this traversal of the list.