text: /*
   * Copyright (c) 2015 - 2022, Intel Corporation
   * SPDX-License-Identifier: BSD-3-Clause
   */
  
  #ifndef GEOPM_ENDPOINT_H_INCLUDE
  #define GEOPM_ENDPOINT_H_INCLUDE
  
  #include <stddef.h>
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  static const size_t GEOPM_ENDPOINT_AGENT_NAME_MAX = 256;
  static const size_t GEOPM_ENDPOINT_PROFILE_NAME_MAX = 256;
  static const size_t GEOPM_ENDPOINT_HOSTLIST_PATH_MAX = 512;
  
  struct geopm_endpoint_c;
  
  /*!
   *  @brief Create an endpoint object for other API functions.
   *
   *  @param [in] endpoint_name Shared memory key substring used to create
   *         an endpoint that an agent can attach to.
   *
   *  @param [out] endpoint Opaque pointer to geopm_endpoint_c object,
   *          or NULL upon failure.
   *
   *  @return Zero on success, error code on failure.
   */
  int geopm_endpoint_create(const char *endpoint_name,
                            struct geopm_endpoint_c **endpoint);
  
  /*!
   *  @brief Release resources associated with endpoint.
   *
   *  Additionally will send a signal to the agent that the manager
   *  is detaching from the policy and will no longer send updates.
   *
   *  @param [in] endpoint Object to be destroyed which was previously
   *         created by call to geopm_endpoint_create().
   *
   *  @return Zero on success, error code on failure.
   */
  int geopm_endpoint_destroy(struct geopm_endpoint_c *endpoint);
  
  /*!
   *  @brief Create shmem regions within the endpoint for policy/sample
   *         handling.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   *
   *  @return Zero on success, error code on failure.
   */
  int geopm_endpoint_open(struct geopm_endpoint_c *endpoint);
  
  /*!
   *  @brief Destroy shmem regions within the endpoint.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   *
   *  @return Zero on success, error code on failure.
   */
  int geopm_endpoint_close(struct geopm_endpoint_c *endpoint);
  
  /*!
   *  @brief Check if an agent has attached.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   *
   *  @param [in] agent_name_max Number of bytes allocated for the
   *         agent_name string.
   *
   *  @param [out] agent_name Name of agent if one has attached to the
   *         endpoint.  If no agent has attached string is unaltered.
   *
   *  @return Zero if endpoint has an agent attached and agent name can
   *          be stored in provided buffer, error code otherwise.  If no
   *          agent has attached, error code GEOPM_ERROR_NO_AGENT is
   *          returned.
   *
   */
  int geopm_endpoint_agent(struct geopm_endpoint_c *endpoint,
                           size_t agent_name_max,
                           char *agent_name);
  
  /*!
   *  @brief Blocks until an agent has attached or the timeout is
   *         reached.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   *
   *  @param [in] timeout Timeout in seconds.
   */
  int geopm_endpoint_wait_for_agent_attach(struct geopm_endpoint_c *endpoint,
                                           double timeout);
  
  /*!
   * @brief Stops any current wait loops the endpoint is running.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   */
  int geopm_endpoint_stop_wait_loop(struct geopm_endpoint_c *endpoint);
  
  /*!
   * @brief Resets the endpoint to prepare for a subsequent call to
   *        geopm_endpoint_wait_for_agent_attach().
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   */
  int geopm_endpoint_reset_wait_loop(struct geopm_endpoint_c *endpoint);
  
  /*!
   *  @brief Check profile name for an attached job.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create().
   *
   *  @param [in] profile_name_max Number of bytes allocated for the
   *         profile_name string.
   *
   *  @param [out] profile_name Profile name of the job if one has
   *         attached to the endpoint.  If no agent has attached string
   *         is unaltered.
   *
   *  @return Zero if endpoint has an agent attached and profile name can
   *          be stored in provided buffer, error code otherwise.  If no
   *          agent has attached, error code GEOPM_ERROR_NO_AGENT is
   *          returned.
   *
   */
  int geopm_endpoint_profile_name(struct geopm_endpoint_c *endpoint,
                                  size_t profile_name_max,
                                  char *profile_name);
  
  /*!
   *  @brief Get the number of nodes managed by the agent.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create() that has reported an attached
   *         agent.
   *
   *  @param [out] num_node Number of compute nodes controled by
   *         attached agent.
   *
   *  @return Zero on success, error code on failure.
   */
  int geopm_endpoint_num_node(struct geopm_endpoint_c *endpoint,
                              int *num_node);
  
  /*!
   *  @brief Get the hostname of the indexed compute node.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create() that has reported an attached
   *         agent.
   *
   *  @param [in] node_idx the index from zero to the value returned by
   *         geopm_agent_num_node() - 1.
   *
   *  @param [in] node_name_max Number of bytes allocated for the
   *         node_name string.
   *
   *  @param [out] node_name The compute node hostname.
   *
   *  @return Zero on success, error code on failure
   */
  int geopm_endpoint_node_name(struct geopm_endpoint_c *endpoint,
                               int node_idx,
                               size_t node_name_max,
                               char *node_name);
  
  /*!
   *  @brief Set the policy values for the agent to follow.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create() that has reported an attached
   *         agent.
   *
   *  @param [in] policy_array Array of length returned by
   *         geopm_agent_num_policy() specifing the value of each policy
   *         parameter.
   *
   *  @return Zero on success, error code on failure
   */
  int geopm_endpoint_write_policy(struct geopm_endpoint_c *endpoint,
                                  size_t num_policy,
                                  const double *policy_array);
  
  
  /*!
   *  @brief Get a sample from the agent and amount of time that has
   *         passed since the agent last provided an update.
   *
   *  @param [in] endpoint Object created by call to
   *         geopm_endpoint_create() that has reported an attached agent
   *         that provides samples (i.e. value given by
   *         geopm_agent_num_sample() is greater than zero).
   *
   *  @param [out] sample_array Array of sampled values provide by the
   *         agent.
   *
   *  @param [out] timestamp The timestamp of the agent's last update to
   *         the sample.
   *
   *  @return Zero on success, error code on failure
   */
  int geopm_endpoint_read_sample(struct geopm_endpoint_c *endpoint,
                                 size_t num_sample,
                                 double *sample_array,
                                 double *sample_age_sec);
  
  #ifdef __cplusplus
  }
  #endif
  #endif
  