apex_api.hpp

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)
 */
 
#pragma once
 
/* required for Doxygen */
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
/* This is annoying and confusing.  We have to set a define so that the
 * HPX config file will be included, which will define APEX_HAVE_HPX
 * for us.  We can't use the same name because then the macro is defined
 * twice.  So, we have a macro to make sure the macro is defined. */
#ifdef APEX_HAVE_HPX_CONFIG
#include <hpx/config.hpp>
#endif
 
#include "apex_types.h"
#include "apex_options.hpp"
#include "apex_export.h"
#include "profiler.hpp"
#include "profile.hpp"
#include "task_wrapper.hpp"
#include <functional>
#include <stdio.h>
#include <string>
#include <set>
#include <vector>
#include <memory>
#include <sstream>
#include <utility>
#include <stdint.h>
 
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
class apex_tuning_request;
 
namespace apex
{
 
static std::shared_ptr<task_wrapper> null_task_wrapper(nullptr);
 
// These are all static functions for the class. There should be only
// one APEX object in the process space.
 
APEX_EXPORT uint64_t init(const char * thread_name,
    const uint64_t comm_rank, const uint64_t comm_size);
 
APEX_EXPORT std::string dump(bool reset);
 
APEX_EXPORT void finalize(void);
 
APEX_EXPORT void cleanup(void);
 
/*
 * Functions for starting, stopping timers
 */
 
APEX_EXPORT profiler * start(const std::string &timer_name);
 
APEX_EXPORT profiler * start(const apex_function_address function_address);
 
APEX_EXPORT void start(std::shared_ptr<task_wrapper> task_wrapper_ptr);
 
APEX_EXPORT void stop(profiler * the_profiler, bool cleanup=true);
 
APEX_EXPORT void stop(std::shared_ptr<task_wrapper> task_wrapper_ptr);
 
APEX_EXPORT void yield(profiler * the_profiler);
 
APEX_EXPORT void yield(std::shared_ptr<task_wrapper> task_wrapper_ptr);
 
APEX_EXPORT profiler * resume(const std::string &timer_name);
 
APEX_EXPORT profiler * resume(const apex_function_address function_address);
 
APEX_EXPORT void resume(std::shared_ptr<task_wrapper> task_wrapper_ptr);
 
/*
 * Functions for resetting timer values
 */
 
APEX_EXPORT void reset(const std::string &timer_name);
 
APEX_EXPORT void reset(apex_function_address function_address);
 
APEX_EXPORT void set_state(apex_thread_state state);
 
/*
 * Function for sampling a counter value
 */
 
APEX_EXPORT void sample_value(const std::string &name, double value);
 
APEX_EXPORT std::shared_ptr<task_wrapper> new_task(
    const std::string &name,
    const uint64_t task_id = UINTMAX_MAX,
    const std::shared_ptr<apex::task_wrapper> parent_task = null_task_wrapper);
 
APEX_EXPORT std::shared_ptr<task_wrapper> new_task(
    const apex_function_address function_address,
    const uint64_t task_id = UINTMAX_MAX,
    const std::shared_ptr<apex::task_wrapper> parent_task = null_task_wrapper);
 
APEX_EXPORT std::shared_ptr<task_wrapper> update_task(
    std::shared_ptr<task_wrapper> wrapper,
    const std::string &name);
 
APEX_EXPORT std::shared_ptr<task_wrapper> update_task(
    std::shared_ptr<task_wrapper> wrapper,
    const apex_function_address function_address);
 
APEX_EXPORT apex_event_type register_custom_event(const std::string &name);
 
APEX_EXPORT void custom_event(apex_event_type event_type, void * custom_data);
 
/*
 * Utility functions
 */
 
APEX_EXPORT std::string& version(void);
 
APEX_EXPORT void register_thread(const std::string &name);
 
APEX_EXPORT void exit_thread(void);
 
/*
 * Policy Engine functions.
 */
 
APEX_EXPORT apex_policy_handle* register_policy(const apex_event_type when,
    std::function<int(apex_context const&)> f);
 
APEX_EXPORT std::set<apex_policy_handle*> register_policy(
    std::set<apex_event_type> when, std::function<int(apex_context const&)> f);
 
APEX_EXPORT apex_policy_handle* register_periodic_policy(
    unsigned long period, std::function<int(apex_context const&)> f);
 
APEX_EXPORT apex_policy_handle* sample_runtime_counter(
    unsigned long period, const std::string & counter_name);
 
 
APEX_EXPORT void deregister_policy(apex_policy_handle * handle);
 
APEX_EXPORT void stop_all_async_threads(void);
 
APEX_EXPORT apex_profile* get_profile(apex_function_address function_address);
 
APEX_EXPORT apex_profile* get_profile(const std::string &timer_name);
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
/* Disabled, after adding task_identifier support */
//APEX_EXPORT std::vector<std::string> get_available_profiles();
 
APEX_EXPORT double current_power_high(void);
 
#endif // DOXYGEN_SHOULD_SKIP_THIS
 
APEX_EXPORT int setup_power_cap_throttling(void);      // initialize
 
APEX_EXPORT int setup_timer_throttling(apex_function_address the_address,
        apex_optimization_criteria_t criteria,
        apex_optimization_method_t method, unsigned long update_interval);
 
APEX_EXPORT int setup_throughput_tuning(apex_function_address the_address,
        apex_optimization_criteria_t criteria,
        apex_event_type event_type, int num_inputs, long ** inputs, long * mins,
        long * maxs, long * steps);
 
APEX_EXPORT apex_tuning_session_handle setup_custom_tuning(
        std::function<double(void)> metric, apex_event_type event_type, int
        num_inputs, long ** inputs, long * mins, long * maxs, long * steps);
 
APEX_EXPORT apex_tuning_session_handle setup_custom_tuning(
    apex_tuning_request & request);
 
APEX_EXPORT int setup_timer_throttling(const std::string &the_name,
    apex_optimization_criteria_t criteria, apex_optimization_method_t method,
    unsigned long update_interval);
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
APEX_EXPORT int startup_throttling(void);
#endif
 
APEX_EXPORT int shutdown_throttling(void);   // terminate
 
APEX_EXPORT int get_thread_cap(void);             // for thread throttling
#ifndef DOXYGEN_SHOULD_SKIP_THIS // test API stuff
APEX_EXPORT int get_input2(void);             // for thread throttling
#endif
 
APEX_EXPORT void set_thread_cap(int new_cap);             // for thread throttling
 
 
APEX_EXPORT std::vector<std::pair<std::string,long*>> &
    get_tunable_params(apex_tuning_session_handle h);
 
APEX_EXPORT bool has_session_converged(apex_tuning_session_handle handle);
 
APEX_EXPORT void get_best_values(apex_tuning_session_handle h);
 
APEX_EXPORT void print_options(void);
 
APEX_EXPORT void send (uint64_t tag, uint64_t size, uint64_t target);
 
APEX_EXPORT void recv (uint64_t tag, uint64_t size,
    uint64_t source_rank, uint64_t source_thread);
 
class scoped_timer {
    private:
        std::shared_ptr<apex::task_wrapper> twp;
        bool timing;
    public:
        scoped_timer(uint64_t func) : twp(nullptr), timing(true) {
            twp = apex::new_task((apex_function_address)func);
            apex::start(twp);
        }
        scoped_timer(std::string func) : twp(nullptr), timing(true) {
            twp = apex::new_task(func);
            apex::start(twp);
        }
        scoped_timer(uint64_t func, std::shared_ptr<apex::task_wrapper> parent)
            : twp(nullptr), timing(true) {
            twp = apex::new_task((apex_function_address)func, UINTMAX_MAX, parent);
            apex::start(twp);
        }
        scoped_timer(std::string func,
            std::shared_ptr<apex::task_wrapper> parent)
            : twp(nullptr), timing(true) {
            twp = apex::new_task(func, UINTMAX_MAX, parent);
            apex::start(twp);
        }
        void start(void) {
            if (!timing) {
                apex::start(twp);
                timing = true;
            }
        }
        void stop(void) {
            if (timing) {
                apex::stop(twp);
                timing = false;
            }
        }
        void yield(void) {
            if (timing) {
                apex::yield(twp);
                timing = false;
            }
        }
        void resume(void) {
            if (!timing) {
                apex::resume(twp);
                timing = true;
            }
        }
        ~scoped_timer() {
            stop();
        }
 
        std::shared_ptr<apex::task_wrapper> get_task_wrapper(void) {
            return twp;
        }
};
 
class scoped_thread {
public:
    scoped_thread(const std::string& thread_name) {
        apex::register_thread(thread_name);
    }
    ~scoped_thread() {
        apex::exit_thread();
    }
};
 
} //namespace apex
 
#define APEX_SCOPED_TIMER \
    std::ostringstream _s_foo; \
    _s_foo << __func__ << " [" << __FILE__ << ":" << __LINE__ << "]"; \
    apex::scoped_timer __foo(_s_foo.str());