apex.h

Go to the documentation of this file.

/*
 * Copyright (c) 2014-2020 Kevin Huck
 * Copyright (c) 2014-2020 University of Oregon
 *
 * Distributed under the Boost Software License, Version 1.0. (See accompanying
 * file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 */
 
/*  Copyright (c) 2014 University of Oregon
 *
 */
 
/* required for Doxygen */
 
/*
 * APEX external API
 *
 */
 
/*
 * The C API is required for HPX5 support.
 */
 
#pragma once
 
#ifndef APEX_H
#define APEX_H
 
#include "apex_types.h"
#include "apex_export.h"
#include "stdbool.h"
#include "stdint.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
 * Initialization, finalization functions
 */
 
/* The functions from here on should all be documented by Doxygen. */
 
APEX_EXPORT int apex_init(const char * thread_name, const uint64_t comm_rank,
    const uint64_t comm_size);
 
APEX_EXPORT const char * apex_dump(bool reset);
 
APEX_EXPORT void apex_finalize();
 
APEX_EXPORT void apex_cleanup();
 
/*
 * Functions for starting, stopping timers
 */
 
APEX_EXPORT apex_profiler_handle apex_start(apex_profiler_type type,
    void * identifier);
 
APEX_EXPORT apex_profiler_handle apex_start_guid(apex_profiler_type type,
    void * identifier, uint64_t guid);
 
APEX_EXPORT void apex_stop(apex_profiler_handle profiler);
 
APEX_EXPORT void apex_yield(apex_profiler_handle profiler);
 
APEX_EXPORT apex_profiler_handle apex_resume(apex_profiler_type type,
    void * identifier);
 
APEX_EXPORT apex_profiler_handle apex_resume_guid(apex_profiler_type type,
    void * identifier, uint64_t guid);
 
/*
 * Functions for resetting timer values
 */
 
APEX_EXPORT void apex_reset(apex_profiler_type type, void * identifier);
 
APEX_EXPORT void apex_set_state(apex_thread_state state);
 
/*
 * Function for sampling a counter value
 */
 
APEX_EXPORT void apex_sample_value(const char * name, double value);
 
APEX_EXPORT void apex_new_task(apex_profiler_type type, void * identifier,
    uint64_t task_id);
 
APEX_EXPORT apex_event_type apex_register_custom_event(const char * name);
 
APEX_EXPORT void apex_custom_event(apex_event_type event_type,
    void * custom_data);
 
/*
 * Utility functions
 */
 
APEX_EXPORT const char * apex_version(void);
 
APEX_EXPORT void apex_register_thread(const char * name);
 
APEX_EXPORT void apex_exit_thread(void);
 
/*
 * Policy Engine functions.
 */
 
APEX_EXPORT apex_policy_handle * apex_register_policy(
    const apex_event_type when, apex_policy_function f);
 
APEX_EXPORT apex_policy_handle * apex_register_periodic_policy(
    unsigned long period, apex_policy_function f);
 
APEX_EXPORT void apex_deregister_policy(apex_policy_handle * handle);
 
APEX_EXPORT apex_profile * apex_get_profile(apex_profiler_type type,
    void * identifier);
 
APEX_EXPORT double apex_current_power_high(void);
 
APEX_EXPORT int apex_setup_power_cap_throttling(void);      // initialize
 
APEX_EXPORT 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);
 
APEX_EXPORT 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);
 
APEX_EXPORT int apex_shutdown_throttling(void); // terminate
 
APEX_EXPORT int apex_get_thread_cap(void); // for thread throttling
 
APEX_EXPORT void apex_set_thread_cap(int new_cap); // for thread throttling
 
APEX_EXPORT void apex_print_options(void);
 
APEX_EXPORT void apex_send (uint64_t tag, uint64_t size, uint64_t target);
 
APEX_EXPORT void apex_recv (uint64_t tag, uint64_t size,
    uint64_t source_rank, uint64_t source_thread);
 
APEX_EXPORT uint64_t apex_hardware_concurrency (void);
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
#define apex_macro(name, member_variable, type, default_value) \
void apex_set_##member_variable (type inval); \
type apex_get_##member_variable (void);
FOREACH_APEX_OPTION(apex_macro)
#undef apex_macro
 
#define apex_macro(name, member_variable, type, default_value) \
void apex_set_##member_variable (type inval); \
type apex_get_##member_variable (void);
FOREACH_APEX_STRING_OPTION(apex_macro)
#undef apex_macro
 
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
#ifdef __cplusplus
}
#endif
 
#endif //APEX_H