PaRSEC API #124
Description
Original report by Damien Genet (Bitbucket: dgenet, GitHub: dgenet).
We discussed the API for PaRSEC before the 2.0.0 release.
#!c
/** Struct **/
/* parsec_info_t: hashmap storing <key,value> */
/* keys cover mca parameters, cores, gpu, etc... if there is any etc */
/*! \brief Initialize the parsec platform
*
* Does a lot of stuff. One side effect is setting up the global default_info
* parsec_info_t based on the configuration files, environment variables and command line
* arguments (in this order) as MCA parameters.
*
* @param[in] argc: argc
* @param[in] argv: argv
*
* @return 0 if the underlying runtime has been able to correctly load local resources, a negative value otherwise.
*/
int32_t parsec_init(int argc, char *argv[]);
/*! \brief Stops the platform.
*
* Stops the platform. It's assumed that context and taskpools have been stopped before.
*/
void parsec_fini(void);
/*! \brief Allocate and copy the global information
*
* Provide a new information structure for further modification.
* This call is optional. The global info struct is the default configuration for a context.
*
* @return a deep copy of the info struct
*/
parsec_info_t* parsec_info_copy(void);
/*! \brief Set a key, value pair in the info.
*
* Set a key, value pair in the info. If the key is already present in the info it's value is
* updated and the old value is released. This function makes a copy of both the
* key and the value string.
*
* @param[in] info: the affected info object
* @param[in] key: the key to be used
* @param[in] value: the value to be associated with the key
*
* @return 0 if the key has been successfully set, a negative value otherwise (in which
* case the key and value have not been updated).
*/
int32_t parsec_info_set(parsec_info_t* info, char* key, char* value);
/*! \brief Unset a key, value pair in the info.
*
* Unset a key from the info. If the key is present it will be released, otherwise the
* function return an error and not other outcome is expected.
*
* @return 0 if the key has been successfully removed and all strings (key and value)
* released, a negative value otherwise (in which case the status of the key is unknown).
*/
int32_t parsec_info_unset(parsec_info_t* info, char* key);
/*! \brief Get the value of a key from the info.
*
* Get the value associated with a key from the info. If the key is not present the function
* will return an error. The caller must take care not to modify this string, since that
* would change the info of the process.
*
* @return 0 if the key has been found, a negative value otherwise (the key is not present). If
* the return is 0, the value has been updated with the corresponding value of the key
* (including a potential NULL if the key was associated with NULL).
*/
int32_t parsec_info_get(parsec_info_t* info, char* key, const char** value);
/*! \brief Release an info object
*
* Release an info object including all the internal keys and values. This function does not fail.
*/
void parsec_info_free(parsec_info_t** info);
/*! Initialize a context based on information stored in the info struct.
*
* @param[in] info: pointer to an info structure.
*
* @return a pointer to a new parsec_context_t object representing the set of resources
* described in the info structure
*/
parsec_context_t* parsec_context_init(parsec_info_t* info);
/*! Return an info struct pointer to the actual set of resources that have been assembled in the VM.
*
* @param[in] context
*
* @return a pointer to an info struct
*/
parsec_info_t* parsec_context_getinfo(parsec_context_t* context);
/*! \brief Start the context.
*
* @param[in] context
*
* @return nothing but has a few side effects.
*/
void parsec_context_start(parsec_context_t* context);
/*! \brief Blocking call. The main thread enters the dance.
* The main thread enters the scheduling loop and join the other threads
* to progress the context. This call returns when ALL the taskpools enqueued
* in the context has been flushed from tasks.
*
* @param[in] context
*/
void parsec_context_wait(parsec_context_t* context);
/*! Non blocking call probing the execution status of the context
*
* @param[in] context
*/
void parsec_context_status(parsec_context_t* context);
/*! \brief Build a PTG taskpool.
*
* @return taskpool
*/
parsec_taskpool_t* parsec_taskpool_ptg_new();
/*! \brief Build a DTD taskpool.
* Build an empty DTD taskpool to enable the insertion of tasks.
*
* @return taskpool
*/
parsec_taskpool_t* parsec_taskpool_dtd_new();
/*! \brief Free the taskpool from the user point of vue.
*
* The reference counter of the taskpool is decremented. Memory is free'd when needed.
*
* @param[in] taskpool
*/
void parsec_taskpool_release(parsec_taskpool_t* tp);
/*! \brief Enqueue the taskpool in the context.
*
* Enqueue the taskpool in the context will enable the scheduling of the taskpool tasks.
* The unique identifier serves the identification of the tuple (context, taskpool) in
* a distributed context.
*
* @param[inout] context
* @param[inout] taskpool
* @param[in] key: globally unique identifier
*/
void parsec_context_add_taskpool(parsec_context_t* context, parsec_taskpool_t* taskpool, parsec_key_t key);
/*! \brief Blocking call waiting for the completion of a specific taskpool.
*
* The calling thread will join the context to help the completion of the given taskpool.
* Does it mean that this thread will only progress this taskpool?
* Can it progress other taskpool if tasks of other taskpool happen to be ready?
* The call returns when the input taskpool has been flushed from its tasks.
*
* @param[in] taskpool
*/
void parsec_taskpool_wait(parsec_taskpool_t* taskpool);
/*! \brief Test and participate for a short time in the progress of the input taskpool
*
* The calling thread will join the context to help the completion of the given taskpool.
* BUT its participation won't last, the call is supposed non blocking.
* The call returns whether or not the input taskpool has been flushed from its tasks.
*
* @param[in] boolean: either the taskpool is empty or not
*/
int parsec_taskpool_test(parsec_taskpool_t* tp);