Monitoring Composition

All monitoring of a SmartSockets project goes through RTserver. Typically, a request for particular information is sent to RTserver, then RTserver proceeds in one of these ways:

A request is initiated either:

Issuing a command in RTmon or calling a monitoring API function results in a message, specifying the request, being sent to RTserver. These standard messages for requesting information should never be constructed. You should always use an API function or RTmon command to initiate a monitoring message.

To initiate a monitoring request in an RTclient, call one of the functions in the TipcMon* API. This sends a message of type MON_*_SET_WATCH (if watching) or MON_*_POLL_CALL (if polling) to RTserver. The information is returned to the program by an RTserver using a MON_*_STATUS or MON_*_POLL_RESULT message. When the information returns, an RTclient message process callback (created with TipcSrvProcessCbCreate) can be used to process the message. Complete examples of polling and watching for information are shown in the sections Polling and Watching.

Where Monitoring Information Resides

The requested information resides in either an RTserver or an RTclient. Information that resides in an RTserver, to which your client is directly connected, is expected to be returned quickly. These are examples of the information that reside in an RTserver:

These are examples of information that resides in an RTclient:

Information that resides in an RTclient or an indirect RTserver may or may not come back quickly, depending on how busy the RTclient or the RTserver is. If many incoming messages are buffered for an RTclient, the monitoring request message is put on the queue of RTclient in priority order and is processed just like any other message. If the queue is long, it can be some time before the request is serviced and the results returned to the requesting program. The best way to ensure that monitoring requests are serviced quickly is to assign high priorities to the monitoring message types.

By default, all monitoring message types are initialized to the message type priority (if set) or to the value of the option Default_Msg_Priority (if the message type priority is unknown). If nothing is done to change the priority of a monitoring message type, all monitoring requests are issued with priority zero (the default value of the Default_Msg_Priority option in the RTclient issuing the request). This can be changed using the TipcMtSetPriority API call, as described in Priority, to change the priority of the MON_*_POLL_CALL and MON_*_SET_WATCH message types. In a similar manner, the information returned can be given higher priority by changing the priority on the MON_*_POLL_RESULT and MON_*_STATUS message types, which are described in detail later in this chapter.

Specifying Items to be Monitored

In TipcMon*Poll or TipcMon*SetWatch functions, common parameters are the names of the RTclient, RTserver, subject, message type, or option to monitor. The parameter can be the name of a specific type of object to monitor, a wildcarded subject name to select multiple objects (for RTclient and RTserver names only), or the constant T_IPC_MON_ALL. T_IPC_MON_ALL is used to specify all objects of a certain type or all objects matching the wildcarded value in the option Monitor_Scope (see the next section for details). In addition, the TipcMon* functions with no parameters (such as TipcMonServerNamesPoll) also can be thought of as having an implicit parameter, which is always T_IPC_MON_ALL.

The name parameter should be specified as a string (T_STR) and follow these rules:

When a wildcarded value or the T_IPC_MON_ALL value is used, the request is sent to all matching RTclients and RTservers that hold the information. In this case, there are multiple responses and an RTclient message process callback should be used to process the results.

If a poll is initiated on an item that does not exist (for example, no subject exists that matches subject_name), the poll fails and no message is returned. If a watch is initiated on an item that does not exist, RTserver or RTclient saves the request and services it once the item becomes available. In both polls and watchs, it is dangerous to block indefinitely and wait for the result of a poll or watch to come back. Always give a finite timeout when waiting for monitoring results to return.

Monitor Scope and T_IPC_MON_ALL

The Monitor_Scope option specifies the level of interest for SmartSockets monitoring in those monitoring categories with no parameters (such as RTclient names poll) or an RTclient or RTserver parameter of T_IPC_MON_ALL (such as RTclient time watch). Monitor_Scope acts as a filter that prevents a large project from overloading a monitoring program. The default is "/*", which matches all subject names at the first level of the hierarchical subject namespace. All monitoring information is enabled (all filtering is disabled) if Monitor_Scope is set to "/...", which matches all names. The value "/..." should be used with caution on large projects, as this gathers monitoring information for the entire project, and may cause noticeable performance degradation.

RTclient and RTserver monitoring parameters allow a wildcard subject name to be used for matching because the unique subject of an RTserver or RTclient cannot be a wildcarded value. Subject monitoring parameters do not allow a wildcard subject name to be used for matching because subject names can use wildcards, and thus wildcard subject names in monitoring requests are treated literally and are not expanded to all matching subjects. For example, a monitoring request to watch all subscribers to the subject "/stocks/..." is ambiguous (that is, does the monitoring request want only the subscribers for the wildcard subject "/stocks/..." or the subscribers for all subjects matching "/stocks/..."?). There is a way to get a matching list for subject monitoring through the use of the T_IPC_MON_ALL value, in which case all subjects matching the value of the option Monitor_Scope are used.

The Monitor_Scope option is not used for option names and message type names, but these two types instead use T_IPC_MON_ALL to indicate that all objects should be monitored. T_IPC_MON_ALL has two meanings:

The Monitor_Scope option makes it easy to write programs with T_IPC_MON_ALL to monitor a certain portion of the hierarchical subject namespace. Simply by changing Monitor_Scope (for example, from "/stocks/computers/..." to "/stocks/auto/..."), the entire T_IPC_MON_ALL-using program can change its monitoring focus without any code changes.

Watching or Polling: When to Use

As described earlier, information is either polled or watched. Polling should be used in these situations:

Watching, on the other hand, should be used in these situations:

Of course, watching and polling can be used together within the same RTclient to gather information as needed.

Monitoring Message Types

The core of SmartSockets monitoring is the message types. The message types can be thought of as describing the monitoring protocol function. These message types are accessible through various bindings: a C API, a C++ API, and the RTmon command interface.

These message types fall into one of these general categories:

The table lists the monitoring message types and their associated grammar. The T_MT_ prefix is omitted from the message types for the sake of brevity.