2 * Utilities and interfaces for managing POSIX threads within FRR.
3 * Copyright (C) 2017 Cumulus Networks, Inc.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; see the file COPYING; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 #ifndef _FRR_PTHREAD_H
21 #define _FRR_PTHREAD_H
24 #include "frratomic.h"
28 DECLARE_MTYPE(FRR_PTHREAD
);
29 DECLARE_MTYPE(PTHREAD_PRIM
);
31 #define OS_THREAD_NAMELEN 16
34 struct frr_pthread_attr
;
36 struct frr_pthread_attr
{
37 void *(*start
)(void *);
38 int (*stop
)(struct frr_pthread
*, void **);
44 * Mutex protecting this structure. Must be taken for reading some
45 * fields, denoted by a 'Requires: mtx'.
52 /* thread master for this pthread's thread.c event loop */
53 struct thread_master
*master
;
55 /* caller-specified data; start & stop funcs, name, id */
56 struct frr_pthread_attr attr
;
59 * Notification mechanism for allowing pthreads to notify their parents
60 * when they are ready to do work. This mechanism has two associated
63 * - frr_pthread_wait_running()
64 * This function should be called by the spawning thread after
65 * frr_pthread_run(). It safely waits until the spawned thread
66 * indicates that is ready to do work by posting to the condition
69 * - frr_pthread_notify_running()
70 * This function should be called by the spawned thread when it is
71 * ready to do work. It will wake up any threads waiting on the
72 * previously described condition.
74 pthread_cond_t
*running_cond
;
75 pthread_mutex_t
*running_cond_mtx
;
79 * Fake thread-specific storage. No constraints on usage. Helpful when
80 * creating reentrant pthread implementations. Can be used to pass
81 * argument to pthread entry function.
88 * Human-readable thread name.
94 /* Used in pthread_set_name max 16 characters */
95 char os_name
[OS_THREAD_NAMELEN
];
98 extern struct frr_pthread_attr frr_pthread_attr_default
;
101 * Initializes this module.
103 * Must be called before using any of the other functions.
105 void frr_pthread_init(void);
108 * Uninitializes this module.
110 * Destroys all registered frr_pthread's and internal data structures.
112 * It is safe to call frr_pthread_init() after this function to reinitialize
115 void frr_pthread_finish(void);
118 * Creates a new frr_pthread with the given attributes.
120 * The 'attr' argument should be filled out with the desired attributes,
121 * including ID, start and stop functions and the desired name. Alternatively,
122 * if attr is NULL, the default attributes will be used. The pthread will be
123 * set up to run a basic threadmaster loop and the name will be "Anonymous".
124 * Scheduling tasks onto the threadmaster in the 'master' field of the returned
125 * frr_pthread will cause them to run on that pthread.
127 * @param attr - the thread attributes
128 * @param name - Human-readable name
129 * @param os_name - 16 characters (including '\0') thread name to set in os,
130 * @return the created frr_pthread upon success, or NULL upon failure
132 struct frr_pthread
*frr_pthread_new(struct frr_pthread_attr
*attr
,
133 const char *name
, const char *os_name
);
136 * Changes the name of the frr_pthread as reported by the operating
139 * @param fpt - the frr_pthread to operate on
140 * @return - on success returns 0 otherwise nonzero error number.
142 int frr_pthread_set_name(struct frr_pthread
*fpt
);
145 * Destroys an frr_pthread.
147 * Assumes that the associated pthread, if any, has already terminated.
149 * @param fpt - the frr_pthread to destroy
151 void frr_pthread_destroy(struct frr_pthread
*fpt
);
154 * Creates a new pthread and binds it to a frr_pthread.
156 * This function is a wrapper for pthread_create. The first parameter is the
157 * frr_pthread to bind the created pthread to. All subsequent arguments are
158 * passed unmodified to pthread_create(). The frr_pthread * provided will be
159 * used as the argument to the pthread entry function. If it is necessary to
160 * pass additional data, the 'data' field in the frr_pthread may be used.
162 * This function returns the same code as pthread_create(). If the value is
163 * zero, the provided frr_pthread is bound to a running POSIX thread. If the
164 * value is less than zero, the provided frr_pthread is guaranteed to be a
165 * clean instance that may be susbsequently passed to frr_pthread_run().
167 * @param fpt - frr_pthread * to run
168 * @param attr - see pthread_create(3)
170 * @return see pthread_create(3)
172 int frr_pthread_run(struct frr_pthread
*fpt
, const pthread_attr_t
*attr
);
175 * Waits until the specified pthread has finished setting up and is ready to
178 * If the pthread's code makes use of the startup synchronization mechanism,
179 * this function should be called before attempting to use the functionality
180 * exposed by the pthread. It waits until the 'running' condition is satisfied
181 * (see struct definition of frr_pthread).
183 * @param fpt - the frr_pthread * to wait on
185 void frr_pthread_wait_running(struct frr_pthread
*fpt
);
188 * Notifies other pthreads that the calling thread has finished setting up and
189 * is ready to begin work.
191 * This will allow any other pthreads waiting in 'frr_pthread_wait_running' to
194 * @param fpt - the frr_pthread * that has finished setting up
196 void frr_pthread_notify_running(struct frr_pthread
*fpt
);
199 * Stops a frr_pthread with a result.
201 * @param fpt - frr_pthread * to stop
202 * @param result - where to store the thread's result, if any. May be NULL if a
203 * result is not needed.
205 int frr_pthread_stop(struct frr_pthread
*fpt
, void **result
);
207 /* Stops all frr_pthread's. */
208 void frr_pthread_stop_all(void);
210 #ifndef HAVE_PTHREAD_CONDATTR_SETCLOCK
211 #define pthread_condattr_setclock(A, B)
214 #endif /* _FRR_PTHREAD_H */