/// @brief Event handler prototype to be implemented by the tool.
///
/// @param[in] event
///     Event handle of triggered event
/// @param[in,out] user_data
///     User data provided on event handle creation
///
typedef (void)(*MPI_T_event_handler_func)(MPI_T_event event,
                                          void*       user_data);


/// @brief Get number of supported events
/// 
/// @param[out] num_events
///     Number of events defined
///
int
MPI_T_event_get_num(int* num_events);

/// @brief Get event information for an event at a given index
///
/// @param[in] index,
///     Event index
/// @param[out] name
///     Unique name of the event
/// @param[out] name_len
///     Length of the name
/// @param[out] desc
///     Description of the event
/// @param[out[ desc_len
///     Length of the string/buffer %desc
/// @param[out] class
///     Event class
/// @param[out] list_of_datatypes
///     List of datatypes used to encode event data
/// @param[out] bind
///     Object type this event is bound to
/// @param[out] synchronous
///     Flag indicating whether this is a synchronous event or not
///
/// @return
///     MPI_T return code
///
/// @note Should synchronicity be specified by its own parameter
///     or should we introduce a 'flags' bitfield?
///
/// @note Who owns/manages the datatype array buffer?
///
/// @note Should we introduce another call to query the datatype array?
///
/// @note Should we allow to return complex/derived datatypes? What are
///     the implications?
///
int
MPI_T_event_get_info(int                index,
                     char*              name,
                     int*               name_len,
                     char*              desc,
                     int*               desc_len,
                     int*               verbosity,
                     MPI_Datatype*      list_of_datatypes,
                     int*               num_elements,
                     int*               bind,
                     int*               synchronous);


/// @brief Get event index for a given name
///
/// @param[in] name
///     NULL-terminated string specifying the event name
/// @param[out] index
///     Event index
///
/// @return
///     MPI_T return code
///
int
MPI_T_event_get_index(char* name, int* index);

/// @brief Create an event session
///
/// @param[out] session
///     Session handle
///
/// @return
///     MPI_T return code
///
/// @note Do we need a session to separate events among stacked
///     tools?
///
int
MPI_T_event_session_create(MPI_T_event_session* session);

/// @brief Free a session and de-register all associated events
///
/// @param[in,out] session
///     Session handle
///
/// @return
///     MPI_T return code
///
/// @note Do we need a session to separate events among stacked
///     tools?
///
int
MPI_T_event_session_free(MPI_T_event_session* session);

/// @brief Register an event for a specific session
///
/// @param[in] session
///     Session handle
/// @param[in] index
///     Event index
/// @param[in] user_data
///     Pointer to user data for this registration
/// @param[out] event
///     New event handle
///
/// @return
///     MPI_T return code
///
/// @note Should this block until success?
///
/// @note Should this rather be calls MPI_T_event_create as it
///     creates an event handle?
///
int
MPI_T_event_register(MPI_T_event_session      session,
                     int                      index,
                     void*                    user_data,
                     MPI_T_event_handler_func event_handler,
                     MPI_T_event*             event);

/// @brief Unregister an event for a specific session
///
/// @param[in] session
///     Session handle
/// @param[in,out] event
///     Event handle to unregister
///
/// @return
///     MPI_T return code
///
/// @note When is this unregistered? When would it be safe to deallocate
///     user_data? Could unregister block until 'done'?
/// 
int
MPI_T_event_unregister(MPI_T_event_session session,
                       MPI_T_event*        event);

/// @brief Start signaling the given event in the given session.
///
/// @param[in]  session
///     Session handle
/// @param[in]  event
///     Event handle
///
/// @return
///     MPI_T return code
///
/// @note What if register does not block and signaling cannot be startet at
///     this moment? Should we return a "NOT_NOW" error code?
///
/// @note Should the tool be notified if an event could not be started?
///     What if this state occurs asynchronously? Notification via callback?
///
int
MPI_T_event_start(MPI_T_event_session session,
                  MPI_T_event_handle  event);

/// @brief Stop signaling the given event in the given session.
///
/// @param[in]  session
///     Session handle
/// @param[in]  event
///     Event handle
///
/// @return
///     MPI_T return code
///
int
MPI_T_event_stop(MPI_T_event_session session,
                 MPI_T_event_handle  event);

/// @brief Read next value from event handle
///
/// @param[in] event_handle
///     Event handle
/// @param[in] datatype
///     Datatype to be read from event data
/// @param[in,out] buffer
///     User-allocated buffer where data is copied to.
///
/// @return
///     MPI_T return code
///
int
MPI_T_event_read(MPI_T_event_handle event,
                 MPI_Datatype       datatype,
                 void*              buffer);