PaRSEC API

[abouteiller]

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);