src/threads/pmix_tsd.h

0001 /*
0002  * Copyright (c) 2007-2013 Los Alamos National Security, LLC.  All rights
0003  *                         reserved.
0004  * Copyright (c) 2008      Cisco Systems, Inc.  All rights reserved.
0005  * Copyright (c) 2015-2017 Research Organization for Information Science
0006  *                         and Technology (RIST). All rights reserved.
0007  * Copyright (c) 2017-2020 Intel, Inc.  All rights reserved.
0008  * Copyright (c) 2021-2022 Nanook Consulting.  All rights reserved.
0009  * $COPYRIGHT$
0010  *
0011  * Additional copyrights may follow
0012  *
0013  * $HEADER$
0014  */
0015
0016 #ifndef PMIX_THREADS_TSD_H
0017 #define PMIX_THREADS_TSD_H
0018
0019 #include "src/include/pmix_config.h"
0020
0021 #include <pthread.h>
0022
0023 #include "pmix_common.h"
0024
0025 BEGIN_C_DECLS
0026
0027 /**
0028  * @file
0029  *
0030  * Thread Specific Datastore Interface
0031  *
0032  * Functions for providing thread-specific datastore capabilities.
0033  */
0034
0035 /**
0036  * Prototype for callback when tsd data is being destroyed
0037  */
0038 typedef void (*pmix_tsd_destructor_t)(void *value);
0039
0040 typedef pthread_key_t pmix_tsd_key_t;
0041
0042 static inline int pmix_tsd_key_delete(pmix_tsd_key_t key)
0043 {
0044     return pthread_key_delete(key);
0045 }
0046
0047 static inline int pmix_tsd_setspecific(pmix_tsd_key_t key, void *value)
0048 {
0049     return pthread_setspecific(key, value);
0050 }
0051
0052 static inline int pmix_tsd_getspecific(pmix_tsd_key_t key, void **valuep)
0053 {
0054     *valuep = pthread_getspecific(key);
0055     return PMIX_SUCCESS;
0056 }
0057
0058 /**
0059  * Create thread-specific data key
0060  *
0061  * Create a thread-specific data key visible to all threads in the
0062  * current process.  The returned key is valid in all threads,
0063  * although the values bound to the key by pmix_tsd_setspecific() are
0064  * allocated on a per-thread basis and persist for the life of the
0065  * calling thread.
0066  *
0067  * Upon key creation, the value NULL is associated with the new key in
0068  * all active threads.  When a new thread is created, the value NULL
0069  * is associated with all defined keys in the new thread.
0070  *
0071  * The destructor parameter may be NULL.  At thread exit, if
0072  * destructor is non-NULL AND the thread has a non-NULL value
0073  * associated with the key, the function is called with the current
0074  * value as its argument.
0075  *
0076  * @param key[out]       The key for accessing thread-specific data
0077  * @param destructor[in] Cleanup function to call when a thread exits
0078  *
0079  * @retval PMIX_SUCCESS  Success
0080  * @retval EAGAIN        The system lacked the necessary resource to
0081  *                       create another thread specific data key
0082  * @retval ENOMEM        Insufficient memory exists to create the key
0083  */
0084 PMIX_EXPORT int pmix_tsd_key_create(pmix_tsd_key_t *key,
0085                                     pmix_tsd_destructor_t destructor);
0086
0087 /**
0088  * Destruct all thread-specific data keys
0089  *
0090  * Destruct all thread-specific data keys and invoke the destructor
0091  *
0092  * This should only be invoked in the main thread.
0093  * This is made necessary since destructors are not invoked on the
0094  * keys of the main thread, since there is no such thing as
0095  * pthread_join(main_thread)
0096  *
0097  * @retval PMIX_SUCCESS  Success
0098  */
0099 PMIX_EXPORT int pmix_tsd_keys_destruct(void);
0100
0101 END_C_DECLS
0102
0103 #endif /* PMIX_MTHREADS_TSD_H */