1 // SPDX-License-Identifier: GPL-2.0-or-later
3 * Utilities and interfaces for managing POSIX threads within FRR.
4 * Copyright (C) 2017 Cumulus Networks, Inc.
11 #include "frratomic.h"
20 #define OS_THREAD_NAMELEN 16
23 struct frr_pthread_attr
;
25 struct frr_pthread_attr
{
26 void *(*start
)(void *);
27 int (*stop
)(struct frr_pthread
*, void **);
33 * Mutex protecting this structure. Must be taken for reading some
34 * fields, denoted by a 'Requires: mtx'.
41 struct rcu_thread
*rcu_thread
;
43 /* thread master for this pthread's thread.c event loop */
44 struct thread_master
*master
;
46 /* caller-specified data; start & stop funcs, name, id */
47 struct frr_pthread_attr attr
;
50 * Notification mechanism for allowing pthreads to notify their parents
51 * when they are ready to do work. This mechanism has two associated
54 * - frr_pthread_wait_running()
55 * This function should be called by the spawning thread after
56 * frr_pthread_run(). It safely waits until the spawned thread
57 * indicates that is ready to do work by posting to the condition
60 * - frr_pthread_notify_running()
61 * This function should be called by the spawned thread when it is
62 * ready to do work. It will wake up any threads waiting on the
63 * previously described condition.
65 pthread_cond_t
*running_cond
;
66 pthread_mutex_t
*running_cond_mtx
;
70 * Fake thread-specific storage. No constraints on usage. Helpful when
71 * creating reentrant pthread implementations. Can be used to pass
72 * argument to pthread entry function.
79 * Human-readable thread name.
85 /* Used in pthread_set_name max 16 characters */
86 char os_name
[OS_THREAD_NAMELEN
];
89 extern const struct frr_pthread_attr frr_pthread_attr_default
;
92 * Initializes this module.
94 * Must be called before using any of the other functions.
96 void frr_pthread_init(void);
99 * Uninitializes this module.
101 * Destroys all registered frr_pthread's and internal data structures.
103 * It is safe to call frr_pthread_init() after this function to reinitialize
106 void frr_pthread_finish(void);
109 * Creates a new frr_pthread with the given attributes.
111 * The 'attr' argument should be filled out with the desired attributes,
112 * including ID, start and stop functions and the desired name. Alternatively,
113 * if attr is NULL, the default attributes will be used. The pthread will be
114 * set up to run a basic threadmaster loop and the name will be "Anonymous".
115 * Scheduling tasks onto the threadmaster in the 'master' field of the returned
116 * frr_pthread will cause them to run on that pthread.
118 * @param attr - the thread attributes
119 * @param name - Human-readable name
120 * @param os_name - 16 characters (including '\0') thread name to set in os,
121 * @return the created frr_pthread upon success, or NULL upon failure
123 struct frr_pthread
*frr_pthread_new(const struct frr_pthread_attr
*attr
,
124 const char *name
, const char *os_name
);
127 * Changes the name of the frr_pthread as reported by the operating
130 * @param fpt - the frr_pthread to operate on
131 * @return - on success returns 0 otherwise nonzero error number.
133 int frr_pthread_set_name(struct frr_pthread
*fpt
);
136 * Destroys an frr_pthread.
138 * Assumes that the associated pthread, if any, has already terminated.
140 * @param fpt - the frr_pthread to destroy
142 void frr_pthread_destroy(struct frr_pthread
*fpt
);
145 * Creates a new pthread and binds it to a frr_pthread.
147 * This function is a wrapper for pthread_create. The first parameter is the
148 * frr_pthread to bind the created pthread to. All subsequent arguments are
149 * passed unmodified to pthread_create(). The frr_pthread * provided will be
150 * used as the argument to the pthread entry function. If it is necessary to
151 * pass additional data, the 'data' field in the frr_pthread may be used.
153 * This function returns the same code as pthread_create(). If the value is
154 * zero, the provided frr_pthread is bound to a running POSIX thread. If the
155 * value is less than zero, the provided frr_pthread is guaranteed to be a
156 * clean instance that may be susbsequently passed to frr_pthread_run().
158 * @param fpt - frr_pthread * to run
159 * @param attr - see pthread_create(3)
161 * @return see pthread_create(3)
163 int frr_pthread_run(struct frr_pthread
*fpt
, const pthread_attr_t
*attr
);
166 * Waits until the specified pthread has finished setting up and is ready to
169 * If the pthread's code makes use of the startup synchronization mechanism,
170 * this function should be called before attempting to use the functionality
171 * exposed by the pthread. It waits until the 'running' condition is satisfied
172 * (see struct definition of frr_pthread).
174 * @param fpt - the frr_pthread * to wait on
176 void frr_pthread_wait_running(struct frr_pthread
*fpt
);
179 * Notifies other pthreads that the calling thread has finished setting up and
180 * is ready to begin work.
182 * This will allow any other pthreads waiting in 'frr_pthread_wait_running' to
185 * @param fpt - the frr_pthread * that has finished setting up
187 void frr_pthread_notify_running(struct frr_pthread
*fpt
);
190 * Stops a frr_pthread with a result.
192 * @param fpt - frr_pthread * to stop
193 * @param result - where to store the thread's result, if any. May be NULL if a
194 * result is not needed.
196 int frr_pthread_stop(struct frr_pthread
*fpt
, void **result
);
198 /* Stops all frr_pthread's. */
199 void frr_pthread_stop_all(void);
201 #ifndef HAVE_PTHREAD_CONDATTR_SETCLOCK
202 #define pthread_condattr_setclock(A, B)
205 /* mutex auto-lock/unlock */
208 * (for short blocks, multiple mutexes supported)
209 * break & return can be used for aborting the block
211 * frr_with_mutex(&mtx, &mtx2) {
217 #define _frr_with_mutex(mutex) \
218 *NAMECTR(_mtx_) __attribute__(( \
219 unused, cleanup(_frr_mtx_unlock))) = _frr_mtx_lock(mutex), \
222 #define frr_with_mutex(...) \
223 for (pthread_mutex_t MACRO_REPEAT(_frr_with_mutex, ##__VA_ARGS__) \
224 *_once = NULL; _once == NULL; _once = (void *)1) \
228 * (more suitable for long blocks, no extra indentation)
230 * frr_mutex_lock_autounlock(&mtx);
233 #define frr_mutex_lock_autounlock(mutex) \
234 pthread_mutex_t *NAMECTR(_mtx_) \
235 __attribute__((unused, cleanup(_frr_mtx_unlock))) = \
236 _frr_mtx_lock(mutex) \
239 static inline pthread_mutex_t
*_frr_mtx_lock(pthread_mutex_t
*mutex
)
241 pthread_mutex_lock(mutex
);
245 static inline void _frr_mtx_unlock(pthread_mutex_t
**mutex
)
249 pthread_mutex_unlock(*mutex
);
257 #endif /* _FRR_PTHREAD_H */