OVATION Macros

OVATION Macros
Milestone Probe Macros
Trace Probe Macros
- OVATION_TRACE_CALL

OVATION provides several run time settings and macros to be able to tune OVATION to individual application's use cases. We will describe the macros supported by the Probe Framework and the individual probes as well.

OVATION Macros

OVATION_FLUSH_ALL_DATAPOINT_CACHES

OVATION_FLUSH_ALL_DATAPOINT_CACHES ()

Description:

The default behavior of OVATION is to send the collected data points to the collector to process immediately. But, OVATION also provides support for caching datapoints before sending them off to the collector via service configurator directive arguments. The macro can be used by the user to manually flush any data points that remain in the cache. In the default case, one need not invoke this macro explicitly.

OVATION_CLEAR_COLLECTOR_LOG

OVATION_CLEAR_COLLECTOR_LOG()

Description:

Clear all data from the Collector.

OVATION_GET_COMPONENT_DESCRIPTION

OVATION_GET_COMPONENT_DESCRIPTION(OBJECT_DESCRIPTION)

Description:	Get the description of the component that contains the object or servant. Returns "Not in a component" if no object-to-component mapping has been set for this object.
Parameters:	OBJECT_DESCRIPTION The description of the object whose component name is being set. This should be the same as one of the object descriptions passed into OVATION_SET_CALLER_DESCRIPTION or OVATION_SET_SERVANT_PTR_DESCRIPTION

OVATION_GET_CURRENT_CALLER_DESCRIPTION

OVATION_GET_CURRENT_CALLER_DESCRIPTION()

Description:

Return the description of the caller (i.e. client-side) object. The description isn't actually associated with an object, the description applies to the current thread in the current scope. These descriptions are very important; the instrumentation code uses them to figure out what the unique names are of all of the distributed objects in the application.

If no description has been set for the current scope, then the object reference's Interface Repository Id is returned.

Parameters:

none

OVATION_GET_CURRENT_CALLER_DESCRIPTION_FOR

OVATION_GET_CURRENT_CALLER_DESCRIPTION_FOR(PROXY)

Description:

Parameters:

PROXY
The calling object reference. If no description has been set for the current scope, then the object reference's Interface Repository Id is returned.

OVATION_GET_SERVANT_PTR_DESCRIPTION

OVATION_GET_SERVANT_PTR_DESCRIPTION(SERVANT_PTR)

Description:	Return the description of the servant (i.e. server-side) object. These descriptions are very important; the instrumentation code uses them to figure out what the unique names are of all of the distributed objects in the application.
Parameters:	SERVANT_PTR A pointer the servant whose description is being set. DESCRIPTION The description of the servant object, as a string. The Distributed Debugger uses these descriptions to uniquely identify distributed objects. Two different objects with the same description are considered to be the same object.

OVATION_RESUME_COLLECTOR

Description:

Resume the suspended Collector. See OVATION_SUSPEND_COLLECTOR for information about suspending a Collector.

OVATION_SET_CLOCK

OVATION_SET_CLOCK(POA_CLOCK)

Description:

Set an alternate servant for the virtual clock. The virtual clock is a system-wide clock which is stopped while debugging information is being collected, and restarted afterwards. The default clock gets the current system time, and cannot be stopped.

If the clock is set, it should be set in the application's main, before any threads are spawned, because this call is not protected by a mutex lock.

To use a remote clock instead, use the -OVATIONClockIOR command-line option.

Parameters:

POA_CLOCK
A pointer to a C++ servant which implements the OVATION_TimeService::Clock IDL interface. The caller of the macro gives up ownership of the clock servant.

OVATION_SET_COMPONENT_DESCRIPTION

OVATION_SET_COMPONENT_DESCRIPTION(OBJECT_DESCRIPTION,COMPONENT_DESCRIPTION)

Description:	Set the description of the component that contains the object or servant. Use this mechanism to indicate which objects or servants are grouped together in the same component.
Parameters:	OBJECT_DESCRIPTION The description of the object whose component name is being set. This should be the same as one of the object descriptions passed into OVATION_SET_CALLER_DESCRIPTION or OVATION_SET_SERVANT_PTR_DESCRIPTION COMPONENT_DESCRIPTION The description of the object's component, as a string. Defaults to "Not in a component"

OVATION_SET_COLLECTION_MEDIATOR

OVATION_SET_COLLECTION_MEDIATOR(POA_MEDIATOR)

Description:

Set an alternate servant for the collection mediator. The mediator mediates communication between the probes and the collector. If not provided, a default mediator is automatically created in the local process.

If the mediator is set, it should be set in the application's main, before any threads are spawned, because this call is not protected by a mutex lock.

To use a remote mediator instead, use the -OVATIONCollectionMediatorIOR command-line option.

This macro is usually not used, and the default mediator is used.

Parameters:

POA_MEDIATOR
A pointer to a C++ servant which implements the OVATION_Instrumentation::CollectionMediator IDL interface. The caller of the macro gives up ownership of the mediator servant.

OVATION_SET_COLLECTOR

OVATION_SET_COLLECTOR(POA_COLLECTOR)

Description:	Set the Collector that collects Distributed Debugging information to a local C++ servant. The Collector implements the OVATION_Instrumentation::Collector IDL interface. This macro is used to set a local Collector. To use a remote collector instead, use the -OVATIONCollectorIOR command-line argument.
Parameters:	POA_COLLECTOR A pointer to a C++ servant which implements the OVATION_Instrumentation::Collector IDL interface. The caller of the macro gives up ownership of the collector servant.

OVATION_SET_CURRENT_CALLER_DESCRIPTION

OVATION_SET_CURRENT_CALLER_DESCRIPTION(DESCRIPTION)

Description:

Sets the description of the caller (i.e. client-side) object. The description isn't actually associated with an object, the description applies to the current thread in the current scope. These descriptions are very important; the instrumentation code uses them to figure out what the unique names are of all of the distributed objects in the application.

If no description is specified, the client description defaults to the calling object reference's Interface Repository ID.

Parameters:

DESCRIPTION
The description of the calling object, as a string. The Distributed Debugger uses these descriptions to uniquely identify distributed objects. Two different scopes with the same description are considered to be the same object

OVATION_SET_CURRENT_CALLER_DESCRIPTION_FROM

OVATION_SET_CURRENT_CALLER_DESCRIPTION_FROM(SERVANT_PTR)

Description:

Sets the description of the caller (i.e. client-side) object by retrieving the description of the servant. The description isn't actually associated with an object; the description applies to the current thread in the current scope. These descriptions are very important; the instrumentation code uses them to figure out what the unique names are of all of the distributed objects in the application.

Parameters:

SERVANT_PTR
Servant whose description is retrieved.

OVATION_SET_CURRENT_THREAD_NAME

OVATION_SET_CURRENT_THREAD_NAME(THREAD_NAME_STR)

Description:	Set the name of the current thread. This name will appear in the debugger's GUIs. Default value is the thread id. This macro should be used inside of the thread, very shortly after the thread starts, before any remote calls are made.
Parameters:	THREAD_NAME_STR Name of the thread, as it will appear in the debugger's GUIs

OVATION_SET_DEFAULT_COMPONENT_DESCRIPTION

OVATION_SET_DEFAULT_COMPONENT_DESCRIPTION(COMPONENT_DESCRIPTION)

Description:	Set the component description of any object for which no description has been provided. Defaults to "Not in a component".
Parameters:	COMPONENT_DESCRIPTION The description of the object's component, as a string. Defaults to "Not in a component"

OVATION_SET_FILTER

OVATION_SET_FILTER (POA_FILTER)

Description:	Set the Filter that is queried before data is sent to the Collector. The default filter allows everything to pass. New filters can be created by implementing the OVATION_Instrumentation::Filter IDL interface. There is one operation, "passes(CollectableDatapoint)", in that IDL interface.
Parameters:	POA_FILTER A pointer to a C++ servant which implements the OVATION_Instrumentation::Filter IDL interface. The caller of the macro gives up ownership of the collector servant.

OVATION_SET_FRAME_RATE

OVATION_SET_FRAME_RATE(VALUE)

Description:	Indicate the frame rate for this particular thread. The Distributed Debugger passes this information to the Collector for each remote method call or event channel event. If not specified, no frame rate information is passed.
Parameters:	VALUE The frame rate for the current thread.

OVATION_SET_PROCESS_NAME

OVATION_SET_PROCESS_NAME(PROCESS_NAME_STR)

Description:	Set the name of the process. This name will appear in the debugger's GUIs. Default value is the name of the executable. This macro should be used after OVATION_INIT, but before any remote calls are made. The best place to use it is immediately after OVATION_INIT.
Parameters:	PROCESS_NAME_STR Name of the process, as it will appear in the debugger's GUIs

OVATION_SET_SERVANT_PTR_DESCRIPTION

OVATION_SET_SERVANT_PTR_DESCRIPTION(SERVANT_PTR,DESCRIPTION)

Description:	Set the description of the servant (i.e. server-side) object. These descriptions are very important; the instrumentation code uses them to figure out what the unique names are of all of the distributed objects in the application. If no description is specified, the client description defaults to the string "SERVER:" followed by the servant's Interface Repository ID.
Parameters:	SERVANT_PTR A pointer the servant whose description is being set. DESCRIPTION The description of the servant object, as a string. The Distributed Debugger uses these descriptions to uniquely identify distributed objects. Two different objects with the same description are considered to be the same object.

OVATION_SET_THREAD_NAME

OVATION_SET_THREAD_NAME(THREAD_ID,THREAD_NAME_STR)

Description:	Set the name of the specified thread. This name will appear in the debugger's GUIs. Default value is the thread's thread id. This macro can be used from any thread, but it should be used before any remote calls are made from the thread whose id is THREAD_ID. A race condition is possible; in many cases, it may make more sense to use OVATION_SET_CURRENT_THREAD_NAME.
Parameters:	THREAD_ID Thread id of the thread whose name is being assigned. THREAD_NAME_STR Name of the thread, as it will appear in the debugger's GUIs

OVATION_SLEEP

OVATION_SLEEP(MILLISECONDS)

Description:	Sleep for the specified number of milliseconds.
Parameters:	MILLISECONDS Length of time to sleep, in milliseconds.

OVATION_STOP_COLLECTOR

Description:

Gracefully shut down the Collector. The Collector's log is NOT written to persistent storage first.

OVATION_SUSPEND_COLLECTOR

OVATION_SUSPEND_COLLECTOR()

Description:

Suspend the Collector. All information passed to the Collector will be ignored.

OVATION_WRITE_COLLECTOR_LOG

OVATION_WRITE_COLLECTOR_LOG(FILE_NAME)

Description:	Write the Collector's collected data to a log file. The log is written in Java Serialization format.
Parameters:	FILE_NAME Name of the file to which the log is written.

OVATION_WRITE_COLLECTOR_LOG_AFTER_CLIENTS_DISCONNECT

OVATION_WRITE_COLLECTOR_LOG_AFTER_CLIENTS_DISCONNECT(FILE_NAME)

Description:

Write the Collector's data to a log file after all processes have completed. The log is written in either Java Serialization format.

This macro doesn't tell the Collector to write the log immediately; instead, it tells the Collector to write the log when all processes sending data to the Collector have exited.

The Collector keeps track of how many processes are sending data to it. When a process gracefully shuts down, it tells the Collector that it is no longer connected.

If a process does not gracefully shut down, it can use the OVATION_FINI macro to cause a graceful shutdown of the Distributed Debugger. OVATION_FINI() could be called from a signal handler that handles SIGINT.

Parameters:

FILE_NAME
Name of the file to which the log is written.

OVATION_WRITE_COLLECTOR_LOG_HIGH_PRIORITY

OVATION_WRITE_COLLECTOR_LOG_HIGH_PRIORITY(FILE_NAME)

Description:	Write the Collector's data to a log file. The log is written in either Java Serialization format. This macro is useful if the Collector is very busy, receiving a high volume of data, and you want to take a snapshot of what it has received so far.
Parameters:	FILE_NAME Name of the file to which the log is written.

Milestone Probe Macros

OVATION_COLLECT_USER_DATA

OVATION_CONDITIONAL_COLLECT_USER_DATA

OVATION_COLLECT_USER_DATA (DATA_DESCRIPTION_STR,
                       VALUE,
                       SOURCE_OBJECT_STR)

OVATION_CONDITIONAL_COLLECT_USER_DATA (CONDITION,
                                   DATA_DESCRIPTION_STR,
                                   VALUE,
                                   SOURCE_OBJECT_STR)

Description:

Allows a user to send his or her own data to the collector. The data will usually be displayed as a single point, with the description and the value.

Indicate that a milestone has been reached. "Milestones" are useful for determining when a series of remotes calls and/or event channel events has concluded. The visualizer draws a vertical line to visually indicate that a milestone has completed. The milestone is timestamped with the time retrieved by the virtual clock.

A conditional "collect user data" allows a condition to be tested before the data is collected. If the condition is TRUE, then the data is collected; if FALSE, the data is ignored.

Parameters:

DATA_DESCRIPTION_STR
A string which describes the data.

VALUE
The value of the data. The value can be anything that can be put into a C++ strstream

SOURCE_OBJECT_STR
A string that contains the description of the object that requested that the data be collected.

CONDITION
A condition that is checked before the data is collected. The data is collected if the condition is true. The condition should be enclosed in parentheses. For example, ((i %3)==0), not (i%3)==0.

OVATION_MILESTONE_IS_REACHED

OVATION_CONDITIONAL_MILESTONE_IS_REACHED

OVATION_MILESTONE_IS_REACHED(MILESTONE_DESCRIPTION_STR,SOURCE_OBJECT_STR)

OVATION_CONDITIONAL_MILESTONE_IS_REACHED (CONDITION,
MILESTONE_DESCRIPTION,
SOURCE_OBJECT_STR)

Description:

Indicate that a milestone has been reached. "Milestones" are useful for determining when a series of remotes calls and/or event channel events has concluded. The visualizer draws a vertical line to visually indicate that a milestone has completed. The milestone is timestamped with the time retrieved by the virtual clock.

A conditional milestone allows a condition to be tested before the milestone is collected. If the condition is TRUE, then the milestone is collected; if FALSE, the milestone is ignored.

Parameters:

MILESTONE_DESCRIPTION_STR
A string which describes the milestone.

SOURCE_OBJECT_STR
A string that contains the description of the object which generated the milestone.

CONDITION
A condition that is checked before the milestone is collected. The milestone is collected if the condition is true. The condition should be enclosed in parentheses. For example, ((i %3)==0), not (i%3)==0.

Trace Probe Macros

OVATION_TRACE_CALL

OVATION_TRACE_CALL (OPERATION_NAME, COMPONENT_NAME, NUM_VALUE, ...)

Description:

Macro to support tracing of CORBA and non-CORBA calls.

Parameters:

OPERATION_NAME
Name of the operation that is being traced

COMPONENT_NAME
Component to which this call belongs to.

NUM_VALUE
Number of arguments that will follow

...
One or more arguments that can be passed to OVATION. The typical values are the arguments of the function call. But, the user is free to send more as needed. The arguments will be shown in the visualizer as parameters to the operation.