Functions

Callback functions — execute a function under specified conditions

Traversal functions — traverse or iterate over a list of items, invoking a processing function on each item

Lookup functions — retrieve pointers to SmartSockets data structures

Access functions — retrieve and set the values of fields within SmartSockets data structures

Callback Functions

Many of the SmartSockets processes make use of callbacks to allow visibility into the internal processing. A callback is a mechanism that allows you to monitor a type of event. The callback can be associated with a certain object or with all objects of a certain type. Callbacks that are 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.

Callback functions do not return a value (the functions are of type void). Callback functions are not used to affect the processing of a process. They are only used to receive notification of some event.

Callbacks have a priority associated with them that allows order to be specified. The priority specifies the order in which callbacks are called. Higher-priority callbacks are called before lower-priority callbacks. 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 that two callbacks cannot be registered that 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 type specific callback data structure, and the third is a user-specified argument that is specified when the callback is created. Depending on the callback type, the first argument may not be used. Check the documentation for the callback being used.

Callbacks are identified by a combination of the callback function and the callback argument. These callbacks are kept in a list that is associated with a particular data structure. All callbacks must be unique within a given list in which they are defined. Subsequent attempts to add the same callback to a given list are ignored.

Global Versus Object-Specific Callbacks

Some types of callbacks can be created for any event of a given type, for example, view-display callbacks. These are called global callbacks. Callbacks can be created specifically (for a specific view) or globally (for all views) such that whenever any view is displayed, the specified callback is called. This is accomplished by specifying a NULL value for the first argument to the callback create function. When both global and specific callbacks are permitted, the object-specific callbacks are merged with the global callback functions, and are called in priority order.

Destruction Management

To streamline SmartSockets processing, callbacks should be destroyed when they are no longer needed. This applies especially for global callbacks, which are invoked for every occurrence of a given event.

Traversals

Another important class of functions in SmartSockets is the traversal functions. These functions traverse or iterate over a list of items, invoking a predefined processing function on each item. An example of this is the function TutHashTraverse. This function calls a specified processing function for each object that exists in the specified hash table. This is useful for dealing with lists of things of indeterminate length.

The function called by the traversal is called with a fixed set of arguments that is unique to each type of traversal. When using these functions, you should be careful to ensure that arguments of the called function meet the specification required for that type of traversal. You must also specify a traversal argument that is passed to the called function, along with the arguments specific to the list being traversed. The traversal argument is not used by the SmartSockets processes and is simply passed on. If a traversal argument is not required, NULL should be specified for the traversal argument.

Traversals continue until all the items in the list have been traversed or (typically) until the called function returns a non-null value. The value thus returned is returned to the caller. For this reason, traversal functions generally return a void pointer, as do functions that induce a traversal. This may also require casting the return from the function that induced the traversal.

During a traversal, do not add or delete elements from the list being traversed.

Lookup Functions

There are a number of functions that perform a lookup to retrieve a pointer to a SmartSockets data structure; for example, TipcMtLookup. Typically, these functions take a name as an argument and return a pointer to the corresponding data structure. Lookup functions must search a list or table of some kind, such as a hash table or linked list. These functions may take a significant amount of time, depending on the type of table being searched and the length of the table or list. It may be more efficient for callers to store values returned from these functions for reuse instead of looking them up every time they are required. In general, lookup functions are not case sensitive.

Access Functions

Access functions are used to obtain fields within SmartSockets data structures, such as TipcMtGetName, and return the name of a specified T_IPC_MT structure. These functions provide public access to SmartSockets data structures and ensure future compatibility with SmartSockets. They are written to be very quick. There is error checking for null pointers (but not invalid pointers) to keep the functions as robust as possible. If there is a problem with the arguments passed to the function, the most likely result is a segmentation fault on UNIX, access violation on OpenVMS, or an application error on Windows.

Access functions are marked as such in their descriptions. Callers can use these functions frequently without causing significant run-time penalties.

The values returned by access functions should be treated as read-only by the calling function. Changing these values produces unpredictable results. For example, the calling function cannot rename a view by getting its name and then writing a new value into the string returned.