src/runtime/pmix_progress_threads.h

0001 /*
0002  * Copyright (c) 2014-2020 Intel, Inc.  All rights reserved.
0003  * Copyright (c) 2015      Cisco Systems, Inc.  All rights reserved.
0004  * Copyright (c) 2021-2022 Nanook Consulting  All rights reserved.
0005  * $COPYRIGHT$
0006  *
0007  * Additional copyrights may follow
0008  *
0009  * $HEADER$
0010  */
0011
0012 #ifndef PMIX_PROGRESS_THREADS_H
0013 #define PMIX_PROGRESS_THREADS_H
0014
0015 #include "pmix_config.h"
0016
0017 #include <pthread.h>
0018 #include <event.h>
0019
0020 #include "src/include/pmix_types.h"
0021
0022 /**
0023  * Initialize a progress thread name; if a progress thread is not
0024  * already associated with that name, start a progress thread.
0025  *
0026  * If you have general events that need to run in *a* progress thread
0027  * (but not necessarily a your own, dedicated progress thread), pass
0028  * NULL the "name" argument to the pmix_progress_thead_init() function
0029  * to glom on to the general PMIX-wide progress thread.
0030  *
0031  * If a name is passed that was already used in a prior call to
0032  * pmix_progress_thread_init(), the event base associated with that
0033  * already-running progress thread will be returned (i.e., no new
0034  * progress thread will be started).
0035  */
0036 PMIX_EXPORT pmix_event_base_t *pmix_progress_thread_init(const char *name);
0037
0038 PMIX_EXPORT pmix_status_t pmix_progress_thread_start(const char *name);
0039
0040 /**
0041  * Stop a progress thread name (reference counted).
0042  *
0043  * Once this function is invoked as many times as
0044  * pmix_progress_thread_init() was invoked on this name (or NULL), the
0045  * progress function is shut down.
0046  * it is destroyed.
0047  *
0048  * Will return PMIX_ERR_NOT_FOUND if the progress thread name does not
0049  * exist; PMIX_SUCCESS otherwise.
0050  */
0051 PMIX_EXPORT pmix_status_t pmix_progress_thread_stop(const char *name);
0052
0053 /**
0054  * Finalize a progress thread name (reference counted).
0055  *
0056  * Once this function is invoked after pmix_progress_thread_stop() has been called
0057  * as many times as pmix_progress_thread_init() was invoked on this name (or NULL),
0058  * the event base associated with it is destroyed.
0059  *
0060  * Will return PMIX_ERR_NOT_FOUND if the progress thread name does not
0061  * exist; PMIX_SUCCESS otherwise.
0062  */
0063 PMIX_EXPORT pmix_status_t pmix_progress_thread_finalize(const char *name);
0064
0065 /**
0066  * Temporarily pause the progress thread associated with this name.
0067  *
0068  * This function does not destroy the event base associated with this
0069  * progress thread name, but it does stop processing all events on
0070  * that event base until pmix_progress_thread_resume() is invoked on
0071  * that name.
0072  *
0073  * Will return PMIX_ERR_NOT_FOUND if the progress thread name does not
0074  * exist; PMIX_SUCCESS otherwise.
0075  */
0076 PMIX_EXPORT pmix_status_t pmix_progress_thread_pause(const char *name);
0077
0078 /**
0079  * Restart a previously-paused progress thread associated with this
0080  * name.
0081  *
0082  * Will return PMIX_ERR_NOT_FOUND if the progress thread name does not
0083  * exist; PMIX_SUCCESS otherwise.
0084  */
0085 PMIX_EXPORT pmix_status_t pmix_progress_thread_resume(const char *name);
0086
0087 #endif