apex_types.h File Reference

#include <stdint.h>
#include <stdbool.h>
#include <unistd.h>

Go to the source code of this file.

Classes
struct	_policy_handle
struct	_context
struct	_profile

Macros
#define	APEX_NULL_PROFILER_HANDLE   (apex_profiler_handle)(nullptr)
#define	APEX_MAX_EVENTS   128
#define	APEX_NULL_FUNCTION_ADDRESS   0L
#define	APEX_IDLE_TIME   "APEX Idle"
#define	APEX_NON_IDLE_TIME   "APEX Non-Idle"
#define	APEX_IDLE_RATE   "APEX Idle Rate"
#define	APEX_DEFAULT_OTF2_ARCHIVE_PATH   "OTF2_archive"
#define	APEX_DEFAULT_OTF2_ARCHIVE_NAME   "APEX"

Typedefs
typedef void *	apex_profiler_handle
typedef uintptr_t	apex_function_address
typedef int(*	apex_policy_function) (apex_context const context)
typedef uint32_t	apex_tuning_session_handle

Enumerations
enum	_apex_profiler_type { APEX_FUNCTION_ADDRESS = 0, APEX_NAME_STRING }
enum	_error_codes { APEX_NOERROR = 0, APEX_ERROR }
enum	_event_type {   APEX_INVALID_EVENT = -1, APEX_STARTUP = 0, APEX_SHUTDOWN, APEX_DUMP,   APEX_RESET, APEX_NEW_NODE, APEX_NEW_THREAD, APEX_EXIT_THREAD,   APEX_START_EVENT, APEX_RESUME_EVENT, APEX_STOP_EVENT, APEX_YIELD_EVENT,   APEX_SAMPLE_VALUE, APEX_SEND, APEX_RECV, APEX_PERIODIC,   APEX_CUSTOM_EVENT_1, APEX_CUSTOM_EVENT_2, APEX_CUSTOM_EVENT_3, APEX_CUSTOM_EVENT_4,   APEX_CUSTOM_EVENT_5, APEX_CUSTOM_EVENT_6, APEX_CUSTOM_EVENT_7, APEX_CUSTOM_EVENT_8,   APEX_UNUSED_EVENT = APEX_MAX_EVENTS }
enum	_thread_state {   APEX_IDLE, APEX_BUSY, APEX_THROTTLED, APEX_WAITING,   APEX_BLOCKED }
enum	apex_optimization_criteria_t { APEX_MAXIMIZE_THROUGHPUT, APEX_MAXIMIZE_ACCUMULATED, APEX_MINIMIZE_ACCUMULATED }
enum	apex_optimization_method_t { APEX_SIMPLE_HYSTERESIS, APEX_DISCRETE_HILL_CLIMBING, APEX_ACTIVE_HARMONY }
enum	_profile_type { APEX_TIMER, APEX_COUNTER }

---

Class Documentation

_policy_handle

struct _policy_handle

A reference to the policy object, so that policies can be "unregistered", or paused later

Class Members
apex_event_type	event_type	The type of policy
int	id	The ID of the policy, used internally to APEX
unsigned long	period	If periodic, the length of the period

_context

struct _context

The APEX context when an event occurs.

Class Members
void *	data	Data associated with the event, such as the custom_data for a custom_event
apex_event_type	event_type	The type of the event currently processing
apex_policy_handle *	policy_handle	The policy handle for the current policy function

_profile

struct _profile

The profile object for a timer in APEX.

Class Members
double	accumulated	Accumulated values for all calls/samples
double	calls	Number of times a timer was called, or the number of samples collected for a counter
double	maximum	Maximum value seen by the timer or counter
double	minimum	Minimum value seen by the timer or counter
double	papi_metrics[8]	Array of accumulated PAPI hardware metrics
double	sum_squares	Running sum of squares calculation for all calls/samples
int	times_reset	How many times was this timer reset
apex_profile_type	type	Whether this is a timer or a counter

Macro Definition Documentation

APEX_DEFAULT_OTF2_ARCHIVE_NAME

#define APEX_DEFAULT_OTF2_ARCHIVE_NAME   "APEX"

Default OTF2 trace name

APEX_DEFAULT_OTF2_ARCHIVE_PATH

#define APEX_DEFAULT_OTF2_ARCHIVE_PATH   "OTF2_archive"

Default OTF2 trace path

APEX_IDLE_RATE

#define APEX_IDLE_RATE   "APEX Idle Rate"

Special profile counter for derived idle rate

APEX_IDLE_TIME

#define APEX_IDLE_TIME   "APEX Idle"

Special profile counter for derived idle time

APEX_MAX_EVENTS

#define APEX_MAX_EVENTS   128

The maximum number of event types. Allows for many custom events.

APEX_NON_IDLE_TIME

#define APEX_NON_IDLE_TIME   "APEX Non-Idle"

Special profile counter for derived non-idle time

APEX_NULL_FUNCTION_ADDRESS

#define APEX_NULL_FUNCTION_ADDRESS   0L

A null pointer representing an APEX function address. Used when a null APEX function address is to be passed in to any apex functions to represent "all functions".

APEX_NULL_PROFILER_HANDLE

#define APEX_NULL_PROFILER_HANDLE   (apex_profiler_handle)(nullptr)

A null pointer representing an APEX profiler handle. Used when a null APEX profile handle is to be passed in to apex::stop when the profiler object wasn't retained locally.

Typedef Documentation

apex_function_address

typedef uintptr_t apex_function_address

Rather than use void pointers everywhere, be explicit about what the functions are expecting.

apex_policy_function

typedef int(* apex_policy_function) (apex_context const context)

Rather than use void pointers everywhere, be explicit about what the functions are expecting.

apex_profiler_handle

typedef void* apex_profiler_handle

The address of a C++ object in APEX. Not useful for the caller that gets it back, but required for stopping the timer later.

apex_tuning_session_handle

typedef uint32_t apex_tuning_session_handle

A handle to a tuning session.

Enumeration Type Documentation

_apex_profiler_type

enum _apex_profiler_type

Enumerator
APEX_FUNCTION_ADDRESS	The ID is a function (or instruction) address
APEX_NAME_STRING	The ID is a character string

_error_codes

enum _error_codes

Typedef for enumerating the different event types

Enumerator
APEX_NOERROR	No error occurred
APEX_ERROR	Some error occurred - check stderr output for details

_event_type

enum _event_type

Enumerator
APEX_STARTUP	APEX is initialized
APEX_SHUTDOWN	APEX is terminated
APEX_DUMP	APEX is dumping output
APEX_RESET	APEX is resetting data structures
APEX_NEW_NODE	APEX has registered a new process ID
APEX_NEW_THREAD	APEX has registered a new OS thread
APEX_EXIT_THREAD	APEX has exited an OS thread
APEX_START_EVENT	APEX has processed a timer start event
APEX_RESUME_EVENT	APEX has processed a timer resume event (the number of calls is not incremented)
APEX_STOP_EVENT	APEX has processed a timer stop event
APEX_YIELD_EVENT	APEX has processed a timer yield event
APEX_SAMPLE_VALUE	APEX has processed a sampled value
APEX_SEND	APEX has processed a send event
APEX_RECV	APEX has processed a recv event
APEX_PERIODIC	APEX has processed a periodic timer
APEX_CUSTOM_EVENT_1	APEX has processed a custom event - useful for large granularity application control events

_profile_type

enum _profile_type

The type of a profiler object

Enumerator
APEX_TIMER	This profile is a instrumented timer
APEX_COUNTER	This profile is a sampled counter

_thread_state

enum _thread_state

Typedef for enumerating the thread states.

Enumerator
APEX_IDLE	Thread is idle
APEX_BUSY	Thread is working
APEX_THROTTLED	Thread is throttled (sleeping)
APEX_WAITING	Thread is waiting for a resource
APEX_BLOCKED	Thread is blocked

apex_optimization_criteria_t

enum apex_optimization_criteria_t

Typedef for enumerating the different optimization strategies for throttling.

Enumerator
APEX_MAXIMIZE_THROUGHPUT	maximize the number of calls to a timer/counter
APEX_MAXIMIZE_ACCUMULATED	maximize the accumulated value of a timer/counter
APEX_MINIMIZE_ACCUMULATED	minimize the accumulated value of a timer/counter

apex_optimization_method_t

enum apex_optimization_method_t

Typedef for enumerating the different optimization methods for throttling.

Enumerator
APEX_SIMPLE_HYSTERESIS	optimize using sliding window of historical observations. A running average of the most recent N observations are used as the measurement.
APEX_DISCRETE_HILL_CLIMBING	Use a discrete hill climbing algorithm for optimization
APEX_ACTIVE_HARMONY	Use Active Harmony for optimization.