#include "apex_types.h"
#include "apex_export.h"
#include "stdbool.h"
#include "stdint.h"

Functions
int	apex_init (const char *thread_name, const uint64_t comm_rank, const uint64_t comm_size)
	Intialize APEX. More...

const char *	apex_dump (bool reset)
	Dump output from APEX. More...

void	apex_finalize ()
	Finalize APEX. More...

void	apex_cleanup ()
	Cleanup APEX. More...

apex_profiler_handle	apex_start (apex_profiler_type type, void *identifier)
	Start a timer. More...

apex_profiler_handle	apex_start_guid (apex_profiler_type type, void *identifier, uint64_t guid)
	Start a timer. More...

void	apex_stop (apex_profiler_handle profiler)
	Stop a timer. More...

void	apex_yield (apex_profiler_handle profiler)
	Stop a timer, but don't increment the number of calls. More...

apex_profiler_handle	apex_resume (apex_profiler_type type, void *identifier)
	Resume a timer. More...

apex_profiler_handle	apex_resume_guid (apex_profiler_type type, void *identifier, uint64_t guid)
	Resume a timer. More...

void	apex_reset (apex_profiler_type type, void *identifier)
	Reset a timer or counter. More...

void	apex_set_state (apex_thread_state state)
	Set the thread state. More...

void	apex_sample_value (const char *name, double value)
	Sample a state value. More...

void	apex_new_task (apex_profiler_type type, void *identifier, uint64_t task_id)
	Create a new task (dependency). More...

apex_event_type	apex_register_custom_event (const char *name)
	Register an event type with APEX. More...

void	apex_custom_event (apex_event_type event_type, void *custom_data)
	Trigger a custom event. More...

const char *	apex_version (void)
	Return the APEX version. More...

void	apex_register_thread (const char *name)
	Register a new thread. More...

void	apex_exit_thread (void)
	Exit a thread. More...

apex_policy_handle *	apex_register_policy (const apex_event_type when, apex_policy_function f)
	Register a policy with APEX. More...

apex_policy_handle *	apex_register_periodic_policy (unsigned long period, apex_policy_function f)
	Register a policy with APEX. More...

void	apex_deregister_policy (apex_policy_handle *handle)
	Deregister a policy with APEX. More...

apex_profile *	apex_get_profile (apex_profiler_type type, void *identifier)
	Get the current profile for the specified id. More...

double	apex_current_power_high (void)
	Get the current power reading. More...

int	apex_setup_power_cap_throttling (void)
	Initialize the power cap throttling policy. More...

int	apex_setup_timer_throttling (apex_profiler_type type, void *identifier, apex_optimization_criteria_t criteria, apex_optimization_method_t method, unsigned long update_interval)
	Setup throttling to optimize for the specified function. More...

int	apex_setup_throughput_tuning (apex_profiler_type type, void identifier, apex_optimization_criteria_t criteria, apex_event_type event_type, int num_inputs, long inputs, long mins, long maxs, long steps)
	Setup throttling to optimize for the specified function, using multiple input criteria. More...

int	apex_shutdown_throttling (void)
	Terminate the throttling policy. More...

int	apex_get_thread_cap (void)
	Get the current thread cap set by the throttling. More...

void	apex_set_thread_cap (int new_cap)
	Set the current thread cap for throttling. More...

void	apex_print_options (void)
	Print the current APEX settings. More...

void	apex_send (uint64_t tag, uint64_t size, uint64_t target)
	Notify APEX that the current thread is sending a parcel/message to another rank/locality/process. More...

void	apex_recv (uint64_t tag, uint64_t size, uint64_t source_rank, uint64_t source_thread)
	Notify APEX that the current thread is receiving a parcel/message from another rank/locality/process. More...

uint64_t	apex_hardware_concurrency (void)
	Get the number of possible threads supported on this system. More...

Function Documentation

◆ apex_cleanup()

void apex_cleanup ( )

Cleanup APEX.

Warning: For best results, this function should be explicitly called to free all memory allocated by APEX. If not explicitly called from the application or runtime, it will be automatically called when the APEX main singleton object is destructed. apex_finalize will be automatically called from apex_cleanup if it has not yet been called.

The cleanup method will free all allocated memory for APEX.

Returns: No return value.

See also: apex_finalize

◆ apex_current_power_high()

double apex_current_power_high ( void )

Get the current power reading.

This function will return the current power level for the node, measured in Watts.

Returns: The current power level in Watts.

◆ apex_custom_event()

void apex_custom_event	(	apex_event_type	event_type,
		void *	custom_data
	)

Trigger a custom event.

This function will pass a custom event to the APEX event listeners. Each listeners' custom event handler will handle the custom event. Policy functions will be passed the custom event name in the event context.

Parameters

event_type	The type of the custom event
custom_data	Data specific to the custom event

Returns: No return value.

See also: apex_register_custom_event

◆ apex_deregister_policy()

void apex_deregister_policy ( apex_policy_handle * handle )

Deregister a policy with APEX.

This function will deregister the specified policy. In order to enable the policy again, it should be registered using apex_register_policy or apex_register_periodic_policy.

Parameters

handle The handle of the policy to be deregistered.

See also: apex_register_policy, apex_register_periodic_policy

◆ apex_dump()

const char* apex_dump ( bool reset )

Dump output from APEX.

The stop measurement method will terminate all measurement and optionally:

print a report to the screen
write a profile to disk (if requested)
output all other visualization data
Parameters

reset Flag indicating whether to reset all statistics (true) or not (false).

Returns
a string containing the output.

See also
apex::finalize

◆ apex_exit_thread()

void apex_exit_thread ( void )

Exit a thread.

For multithreaded applications, exit this thread and clean up.

Warning: Failure to exit a thread with APEX may invalidate statistics.

Returns: No return value.

◆ apex_finalize()

void apex_finalize ( )

Finalize APEX.

The stop measurement method will terminate all measurement and optionally:

print a report to the screen (if requested)
write a profile to disk (if requested)
Returns
No return value.

See also
apex_init

◆ apex_get_profile()

apex_profile* apex_get_profile	(	apex_profiler_type	type,
		void *	identifier
	)

Get the current profile for the specified id.

This function will return the current profile for the specified profiler id. Because profiles are updated out-of-band, it is possible that this profile value is out of date. This profile can be either a timer or a sampled value.

Parameters

type	The type of the address to be returned. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be returned, or a "const char *" pointer to the name of the timer / counter.

Returns: The current profile for that timed function or sampled value.

◆ apex_get_thread_cap()

int apex_get_thread_cap ( void )

Get the current thread cap set by the throttling.

This function will return the current thread cap based on the throttling policy.

Returns: The current thread cap value.

◆ apex_hardware_concurrency()

uint64_t apex_hardware_concurrency ( void )

Get the number of possible threads supported on this system.

This method queries the system to determine how many threads can be executed concurrently without oversubscription.

Returns: number of hardware threads available

◆ apex_init()

int apex_init	(	const char *	thread_name,
		const uint64_t	comm_rank,
		const uint64_t	comm_size
	)

Intialize APEX.

Warning: For best results, this function should be called before any other APEX functions.; Use this version of apex_init when you do not have access to the input arguments.

Parameters

thread_name	The name of the thread, or nullptr. The lifetime of the thread will be timed with a timer using this same name.
comm_rank	The rank of this process within the full distributed application, i.e. MPI rank or HPX locality.
comm_size	The total number of processes within the full distributed application, i.e. MPI comm_size or total number of HPX localities.

Returns: APEX_NOERROR on success, or APEX_ERROR on failure.

See also: apex_finalize

◆ apex_new_task()

void apex_new_task	(	apex_profiler_type	type,
		void *	identifier,
		uint64_t	task_id
	)

Create a new task (dependency).

This function will note a task dependency between the current timer (task) and the new task.

Parameters

type	The type of the address to be reset. This can be one of the apex_profiler_type values.
identifier	The function address of the function of the task, or a "const char *" pointer to the name of the task.
task_id	The ID of the task

Returns: No return value.

◆ apex_print_options()

void apex_print_options ( void )

Print the current APEX settings.

This function will print all the current APEX settings.

◆ apex_recv()

void apex_recv	(	uint64_t	tag,
		uint64_t	size,
		uint64_t	source_rank,
		uint64_t	source_thread
	)

Notify APEX that the current thread is receiving a parcel/message from another rank/locality/process.

This method notifies APEX that the current thread is receiving a parcel/message from another rank/locality/process. The tag is meant to be an identifier for the message, not required to be unique. The source value is the APEX rank of the source of the message.

Parameters

tag	The message identifier
size	The message size (in bytes)
source_rank	The message source (as a rank/locality index)
source_thread	The message source (as a worker thread index)

◆ apex_register_custom_event()

apex_event_type apex_register_custom_event ( const char * name )

Register an event type with APEX.

Create a user-defined event type for APEX.

Parameters

name	The name of the custom event

Returns: The index of the custom event.

See also: apex_custom_event

◆ apex_register_periodic_policy()

apex_policy_handle* apex_register_periodic_policy	(	unsigned long	period,
		apex_policy_function	f
	)

Register a policy with APEX.

Apex provides the ability to call an application-specified function periodically. This assigns the passed in function to be called on a periodic basis. The context for the event will be passed to the registered function.

Parameters

period	How frequently the function should be called
f	The function to be called when that event is handled by APEX.

Returns: A handle to the policy, to be stored if the policy is to be un-registered later.

See also: apex_deregister_policy, apex_register_policy

◆ apex_register_policy()

apex_policy_handle* apex_register_policy	(	const apex_event_type	when,
		apex_policy_function	f
	)

Register a policy with APEX.

Apex provides the ability to call an application-specified function when certain events occur in the APEX library, or periodically. This assigns the passed in function to the event, so that when that event occurs in APEX, the function is called. The context for the event will be passed to the registered function.

Parameters

when	The APEX event when this function should be called
f	The function to be called when that event is handled by APEX.

Returns: A handle to the policy, to be stored if the policy is to be un-registered later.

See also: apex_deregister_policy, apex_register_periodic_policy

◆ apex_register_thread()

void apex_register_thread ( const char * name )

Register a new thread.

For multithreaded applications, register a new thread with APEX.

Warning: Failure to register a thread with APEX may invalidate statistics, and may prevent the ability to use timers or sampled values for this thread.

Parameters

name	The name that will be assigned to the new thread.

Returns: No return value.

◆ apex_reset()

void apex_reset	(	apex_profiler_type	type,
		void *	identifier
	)

Reset a timer or counter.

This function will reset the profile associated with the specified timer or counter id to zero.

Parameters

type	The type of the address to be reset. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be reset, or a "const char *" pointer to the name of the timer / counter.

Returns: No return value.

See also: apex_get_profile

◆ apex_resume()

apex_profiler_handle apex_resume	(	apex_profiler_type	type,
		void *	identifier
	)

Resume a timer.

This function will create a profiler object in APEX, and return a handle to the object. The object will be associated with the name and/or function address passed in to this function. The difference between this function and the apex_start function is that the number of calls to that timer will not be incremented.

Parameters

type	The type of the address to be stored. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be timed, or a "const char *" pointer to the name of the timer.

Returns: The handle for the timer object in APEX. Not intended to be queried by the application. Should be retained locally, if possible, and passed in to the matching apex_stop call when the timer should be stopped.

See also: apex_start, apex_stop, apex_yield

◆ apex_resume_guid()

apex_profiler_handle apex_resume_guid	(	apex_profiler_type	type,
		void *	identifier,
		uint64_t	guid
	)

Resume a timer.

This function will create a profiler object in APEX, and return a handle to the object. The object will be associated with the name and/or function address passed in to this function. The difference between this function and the apex_start function is that the number of calls to that timer will not be incremented.

Parameters

type	The type of the address to be stored. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be timed, or a "const char *" pointer to the name of the timer.
guid	A globally unique identifier for this task.

Returns: The handle for the timer object in APEX. Not intended to be queried by the application. Should be retained locally, if possible, and passed in to the matching apex_stop call when the timer should be stopped.

See also: apex_start, apex_stop, apex_yield

◆ apex_sample_value()

void apex_sample_value	(	const char *	name,
		double	value
	)

Sample a state value.

This function will retain a sample of some value. The profile for this sampled value will store the min, mean, max, total and standard deviation for this value for all times it is sampled.

Parameters

name	The name of the sampled value
value	The sampled value

Returns: No return value.

◆ apex_send()

void apex_send	(	uint64_t	tag,
		uint64_t	size,
		uint64_t	target
	)

Notify APEX that the current thread is sending a parcel/message to another rank/locality/process.

This method notifies APEX that the current thread is sending a parcel/message to another rank/locality/process. The tag is meant to be an identifier for the message, not required to be unique. The target value is the APEX rank of the target of the message.

Parameters

tag	The message identifier
size	The message size (in bytes)
target	The message target (as an APEX rank)

◆ apex_set_state()

void apex_set_state ( apex_thread_state state )

Set the thread state.

This function will set the thread state in APEX for 3rd party observation

Parameters

state The state of the thread.

Returns: No return value.

◆ apex_set_thread_cap()

void apex_set_thread_cap ( int new_cap )

Set the current thread cap for throttling.

This function will set the current thread cap based on an external throttling policy.

Parameters

new_cap The current thread cap value.

◆ apex_setup_power_cap_throttling()

int apex_setup_power_cap_throttling ( void )

Initialize the power cap throttling policy.

This function will initialize APEX for power cap throttling. There are several environment variables that control power cap throttling:

HPX_THROTTLING: If set, throttling will be enabled and initialized at startup.
APEX_THROTTLING_MAX_THREADS: The maximum number of threads the throttling system will allow. The default value is 48.
APEX_THROTTLING_MIN_THREADS: The minimum number of threads the throttling system will allow. The default value is 12.
APEX_THROTTLING_MAX_WATTS: The maximum number of Watts the system can consume as an average rate. The default value is 220.
APEX_THROTTLING_MIN_WATTS: The minimum number of Watts the system can consume as an average rate. The default value is 180.
HPX_ENERGY_THROTTLING: If set, power/energy throttling will be performed.
HPX_ENERGY: TBD

After evaluating the state of the system, the policy will set the thread cap, which can be queried using apex_get_thread_cap().

Returns: APEX_NOERROR on success, otherwise an error code.

◆ apex_setup_throughput_tuning()

int apex_setup_throughput_tuning	(	apex_profiler_type	type,
		void *	identifier,
		apex_optimization_criteria_t	criteria,
		apex_event_type	event_type,
		int	num_inputs,
		long **	inputs,
		long *	mins,
		long *	maxs,
		long *	steps
	)

Setup throttling to optimize for the specified function, using multiple input criteria.

This function will initialize a policy to optimize the specified function, using the list of tunable inputs for the specified function. The optimization criteria include maximizing throughput, minimizing or maximizing time spent in the specified function. After evaluating the state of the system, the policy will assign new values to the inputs.

Parameters

type	The type of the address to be optimized. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be optimized, or a "const char *" pointer to the name of the counter/timer.
criteria	The optimization criteria.
event_type	The apex_event_type that should trigger this policy
num_inputs	The number of tunable inputs for optimization
inputs	An array of addresses to inputs for optimization
mins	An array of minimum values for each input
maxs	An array of maximum values for each input
steps	An array of step values for each input

Returns: APEX_NOERROR on success, otherwise an error code.

◆ apex_setup_timer_throttling()

int apex_setup_timer_throttling	(	apex_profiler_type	type,
		void *	identifier,
		apex_optimization_criteria_t	criteria,
		apex_optimization_method_t	method,
		unsigned long	update_interval
	)

Setup throttling to optimize for the specified function.

This function will initialize the throttling policy to optimize for the specified function. The optimization criteria include maximizing throughput, minimizing or maximizing time spent in the specified function. After evaluating the state of the system, the policy will set the thread cap, which can be queried using apex_get_thread_cap().

Parameters

type	The type of the address to be optimized. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be optimized, or a "const char *" pointer to the name of the counter/timer.
criteria	The optimization criteria.
method	The optimization method.
update_interval	The time between observations, in microseconds.

Returns: APEX_NOERROR on success, otherwise an error code.

◆ apex_shutdown_throttling()

int apex_shutdown_throttling ( void )

Terminate the throttling policy.

This function will terminate the throttling policy.

Returns: APEX_NOERROR on success, otherwise an error code.

◆ apex_start()

apex_profiler_handle apex_start	(	apex_profiler_type	type,
		void *	identifier
	)

Start a timer.

This function will create a profiler object in APEX, and return a handle to the object. The object will be associated with the address or name passed in to this function. If both are zero (null) then the call will fail and the return value will be null.

Parameters

type	The type of the address to be stored. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be timed, or a "const char *" pointer to the name of the timer.

Returns: The handle for the timer object in APEX. Not intended to be queried by the application. Should be retained locally, if possible, and passed in to the matching apex_stop call when the timer should be stopped.

See also: apex_stop, apex_resume, apex_yield

◆ apex_start_guid()

apex_profiler_handle apex_start_guid	(	apex_profiler_type	type,
		void *	identifier,
		uint64_t	guid
	)

Start a timer.

This function will create a profiler object in APEX, and return a handle to the object. The object will be associated with the address or name passed in to this function. If both are zero (null) then the call will fail and the return value will be null.

Parameters

type	The type of the address to be stored. This can be one of the apex_profiler_type values.
identifier	The function address of the function to be timed, or a "const char *" pointer to the name of the timer.
guid	A globally unique identifier for this task.

Returns: The handle for the timer object in APEX. Not intended to be queried by the application. Should be retained locally, if possible, and passed in to the matching apex_stop call when the timer should be stopped.

See also: apex_stop, apex_resume, apex_yield

◆ apex_stop()

void apex_stop ( apex_profiler_handle profiler )

Stop a timer.

This function will stop the specified profiler object, and queue the profiler to be processed out-of-band. The timer value will eventually added to the profile for the process.

Parameters

profiler The handle of the profiler object.

Returns: No return value.

See also: apex_start, apex_yield, apex_resume

◆ apex_version()

const char* apex_version ( void )

Return the APEX version.

Returns: A character string with the APEX version. This string should not be freed after the calling function is done with it.

◆ apex_yield()

void apex_yield ( apex_profiler_handle profiler )

Stop a timer, but don't increment the number of calls.

This function will stop the specified profiler object, and queue the profiler to be processed out-of-band. The timer value will eventually added to the profile for the process. The number of calls will NOT be incremented - this "task" was yielded, not completed. It will be resumed by another thread at a later time.

Parameters

profiler The handle of the profiler object.

Returns: No return value.

See also: apex_start, apex_stop, apex_resume

Functions

Function Documentation

◆ apex_cleanup()

◆ apex_current_power_high()

◆ apex_custom_event()

◆ apex_deregister_policy()

◆ apex_dump()

◆ apex_exit_thread()

◆ apex_finalize()

◆ apex_get_profile()

◆ apex_get_thread_cap()

◆ apex_hardware_concurrency()

◆ apex_init()

◆ apex_new_task()

◆ apex_print_options()

◆ apex_recv()

◆ apex_register_custom_event()

◆ apex_register_periodic_policy()

◆ apex_register_policy()

◆ apex_register_thread()

◆ apex_reset()

◆ apex_resume()

◆ apex_resume_guid()

◆ apex_sample_value()

◆ apex_send()

◆ apex_set_state()

◆ apex_set_thread_cap()

◆ apex_setup_power_cap_throttling()

◆ apex_setup_throughput_tuning()

◆ apex_setup_timer_throttling()

◆ apex_shutdown_throttling()

◆ apex_start()

◆ apex_start_guid()

◆ apex_stop()

◆ apex_version()

◆ apex_yield()