DPCL Class Reference

Chapter 9. Class Phase

Objects of the Phase class represent phases -- the control mechanism for invoking phase probes at set CPU-time intervals.

When a phase is activated, it executes its begin function to initialize any data that may be used during the rest of the phase. If the begin function sends any messages back to the client, those messages invoke the begin callback function. The begin callback function is invoked once per message sent. After the begin function has completed, the data function is then executed, once per datum of probe data associated with the phase. Data is associated with a phase through the Application::alloc_mem or Process::alloc_mem functions. Any messages sent to the client by the data function are handled on the client by the data callback function. When the data function finishes execution for the last datum, the end function is then executed to perform any necessary clean-up operations. Messages sent by the end function are handled by the end callback.

It is important to understand that the Phase object on the client is a data structure that represents the actual phase. The actual phase resides within the instrumented application process. Certain operations, such as alloc_mem, can alter the actual phase in ways that are not reflected within the client data structure. This affects the behavior of the client data structure in subtle ways. In order to provide the most useful abstraction for phases, the default constructor and the copy constructor create new client data structures but they do not create unique phases. As a result, Phase p1, p2; creates a situation where p1 == p2 is regarded as true. Similarly, the sequence Phase p1(f1, f2, t); Phase p2 = p1; also results in p1 == p2 evaluating to true. Similar behavior results when the assignment operator, operator =, is used.

In contrast, the standard constructors create unique phases, even when the parameters used in the constructors are identical. As a result, Phase p1(f1, f2, t), p2(f1, f2, t); results in a situation where p1 == p2 would evaluate to false rather than true. This possibly counter-intuitive behavior is necessary to allow end-user tools to manage separate groups of data on separate timers.

This book uses two terms that you may not be familiar with. The term lhs refers to the left-hand side of an expression or operator, while the term rhs refers to the right-hand side.

Constructors

Synopsis

#include <Phase.h>
Phase(void);
Phase(const Phase &copy);
 
Phase(float period,
        ProbeExp data_func,
        GCBFuncType data_cb,
        GCBTagType data_tg);
 
Phase(float period,
        ProbeExp begin_func,
        GCBFuncType begin_cb,
        GCBTagType begin_tg,
        ProbeExp data_func,
        GCBFuncType data_cb,
        GCBTagType data_tg,
        ProbeExp end_func,
        GCBFuncType end_cb,
        GCBTagType end_tg);

Parameters

copy

phase that will be duplicated in a copy constructor

period

time interval, in seconds (of CPU time), between successive invocations of the phase. This must be a positive value.

begin_func

begin function, executed once, each time the phase is invoked

begin_cb

begin callback, to which any begin function messages are addressed

begin_tag

callback tag for the begin callback, begin_cb

data_func

function that, each time the phase is invoked, is executed after the begin function has completed its execution. The function is executed once for each datum associated with the phase.

data_cb

callback function to which any data function messages are addressed

data_tag

callback tag for the data function callback, data_cb

end_func

end function, executed once per invocation of the phase after the data function has completed its series of executions

end_cb

end callback, to which any end function messages are addressed

end_tag

callback tag for the end callback, end_cb

Description

The default constructor creates an empty phase whose period, functions, callbacks and tags are all set to 0. The default constructor is invoked when uninitialized phases are created, such as in arrays of phases. Objects within the array can be overwritten using an assignment operator (operator =).

The copy constructor is used to transfer the contents of an initialized object (the copy parameter) to an uninitialized object.

The standard constructors create a new phase and new phase data structure, and initialize the data structure according to the parameters that are provided. The Phase function is executed as soon as possible after the phase period elapsed. The underlying operating system does not support periods less than ten milliseconds.

The function prototypes are:

	void begin_func(void *msg_handle);
	void data_func(void *msg_handle, void *data);
	void end_func(void *msg_handle);

Note that the function prototypes above must be signal-safe, and must be loaded into the application before this operation may take place.

Exceptions

ASC_insufficient_memory

a memory allocation routine failed. Insufficient memory to create a new node.

ASC_non_positive_value

period parameter is a non-positive value

ASC_invalid_operand

data_func, begin_func, or end_func parameter is not a function reference

See Also

Application::add_phase, Application::alloc_mem, Application::balloc_mem, Class ProbeModule, Process::add_phase, Process::alloc_mem, Process::balloc_mem

operator =

Synopsis

#include <Phase.h>
Phase &operator = (const Phase &rhs);

Parameters

rhs

right operand

Description

Assigns the value of the right operand to the invoking object. The left operand is the invoking object.

For example,

Phase rhs, lhs; ... lhs = rhs;

assigns the value of rhs to lhs. Then one can be used interchangeably with the other.

Note that assignment is different from creating two phases using the same input values. For example,

Phase p1(x,y,z), p2(x,y,z);

gives two independent phases even though they have exactly the same arguments. Loading p1 into a process and later unloading p1 from the same process is a valid operation. Loading p1 into a process and later unloading p2 from the same process, as if they were the same phase, is invalid. This is because p2 represents a different phase that coincidentally has the same values.

Return Values

A reference to the invoking object (the left operand).

operator ==

Synopsis

#include <Phase.h>
int operator == (const Phase &compare);

Parameters

compare

phase to be compared against the invoking object

Description

This function compares two phases for equivalence. If the two objects represent the same phase, this function returns 1. Otherwise it returns 0.

For example,

Phase rhs, lhs; ... lhs = rhs;

gives a situation where rhs == lhs is true, and operator == returns 1. But

Phase p1(x,y,z), p2(x,y,z);

gives a situation where the value of p1 == p2 is not true, even though they were both constructed with the same values, and operator == returns 0.

Return Values

This function returns 1 if the two objects are equivalent. Otherwise, it returns 0.

operator !=

Synopsis

#include <Phase.h>
int operator != (const Phase &compare);

Parameters

compare

phase to be compared against the invoking object

Description

This function compares two phases for equivalence. If the two objects represent the same phase, this function returns 0. Otherwise it returns 1.

For example,

Phase rhs, lhs; ... lhs = rhs;

gives a situation where rhs != lhs is false, and operator != returns 0. But

Phase p1(x,y,z), p2(x,y,z);

gives a situation where the value of p1 != p2 is true, even though they were both constructed with the same values, and operator != returns 1.

Return Values

This function returns 0 if the two objects are equivalent. Otherwise, it returns 1.