]>
Commit | Line | Data |
---|---|---|
98f14af8 | 1 | /* |
a45dc974 | 2 | * Utilities and interfaces for managing POSIX threads within FRR. |
d8a8a8de | 3 | * Copyright (C) 2017 Cumulus Networks, Inc. |
896014f4 DL |
4 | * |
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. | |
9 | * | |
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. | |
14 | * | |
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 | |
98f14af8 QY |
18 | */ |
19 | ||
20 | #ifndef _FRR_PTHREAD_H | |
21 | #define _FRR_PTHREAD_H | |
22 | ||
23 | #include <pthread.h> | |
a45dc974 | 24 | #include "frratomic.h" |
0bbb9e72 | 25 | #include "memory.h" |
98f14af8 QY |
26 | #include "thread.h" |
27 | ||
a45dc974 | 28 | DECLARE_MTYPE(FRR_PTHREAD); |
0bbb9e72 QY |
29 | DECLARE_MTYPE(PTHREAD_PRIM); |
30 | ||
57019528 CS |
31 | #define OS_THREAD_NAMELEN 16 |
32 | ||
a45dc974 QY |
33 | struct frr_pthread; |
34 | struct frr_pthread_attr; | |
35 | ||
36 | struct frr_pthread_attr { | |
d8a8a8de | 37 | _Atomic uint32_t id; |
a45dc974 QY |
38 | void *(*start)(void *); |
39 | int (*stop)(struct frr_pthread *, void **); | |
a45dc974 QY |
40 | }; |
41 | ||
98f14af8 QY |
42 | struct frr_pthread { |
43 | ||
d8a8a8de QY |
44 | /* |
45 | * Mutex protecting this structure. Must be taken for reading some | |
46 | * fields, denoted by a 'Requires: mtx'. | |
47 | */ | |
48 | pthread_mutex_t mtx; | |
49 | ||
d62a17ae | 50 | /* pthread id */ |
51 | pthread_t thread; | |
98f14af8 | 52 | |
d62a17ae | 53 | /* thread master for this pthread's thread.c event loop */ |
54 | struct thread_master *master; | |
98f14af8 | 55 | |
a45dc974 QY |
56 | /* caller-specified data; start & stop funcs, name, id */ |
57 | struct frr_pthread_attr attr; | |
58 | ||
59 | /* | |
60 | * Notification mechanism for allowing pthreads to notify their parents | |
61 | * when they are ready to do work. This mechanism has two associated | |
62 | * functions: | |
63 | * | |
64 | * - frr_pthread_wait_running() | |
65 | * This function should be called by the spawning thread after | |
66 | * frr_pthread_run(). It safely waits until the spawned thread | |
67 | * indicates that is ready to do work by posting to the condition | |
68 | * variable. | |
69 | * | |
70 | * - frr_pthread_notify_running() | |
71 | * This function should be called by the spawned thread when it is | |
72 | * ready to do work. It will wake up any threads waiting on the | |
73 | * previously described condition. | |
74 | */ | |
75 | pthread_cond_t *running_cond; | |
76 | pthread_mutex_t *running_cond_mtx; | |
77 | _Atomic bool running; | |
78 | ||
79 | /* | |
80 | * Fake thread-specific storage. No constraints on usage. Helpful when | |
81 | * creating reentrant pthread implementations. Can be used to pass | |
82 | * argument to pthread entry function. | |
d8a8a8de QY |
83 | * |
84 | * Requires: mtx | |
a45dc974 QY |
85 | */ |
86 | void *data; | |
d8a8a8de QY |
87 | |
88 | /* | |
89 | * Human-readable thread name. | |
90 | * | |
91 | * Requires: mtx | |
92 | */ | |
93 | char *name; | |
57019528 CS |
94 | |
95 | /* Used in pthread_set_name max 16 characters */ | |
96 | char os_name[OS_THREAD_NAMELEN]; | |
98f14af8 QY |
97 | }; |
98 | ||
a45dc974 QY |
99 | extern struct frr_pthread_attr frr_pthread_attr_default; |
100 | ||
101 | /* | |
102 | * Initializes this module. | |
98f14af8 QY |
103 | * |
104 | * Must be called before using any of the other functions. | |
105 | */ | |
106 | void frr_pthread_init(void); | |
107 | ||
a45dc974 QY |
108 | /* |
109 | * Uninitializes this module. | |
98f14af8 QY |
110 | * |
111 | * Destroys all registered frr_pthread's and internal data structures. | |
112 | * | |
113 | * It is safe to call frr_pthread_init() after this function to reinitialize | |
114 | * the module. | |
115 | */ | |
116 | void frr_pthread_finish(void); | |
117 | ||
a45dc974 QY |
118 | /* |
119 | * Creates a new frr_pthread with the given attributes. | |
98f14af8 | 120 | * |
a45dc974 QY |
121 | * The 'attr' argument should be filled out with the desired attributes, |
122 | * including ID, start and stop functions and the desired name. Alternatively, | |
123 | * if attr is NULL, the default attributes will be used. The pthread will be | |
124 | * set up to run a basic threadmaster loop and the name will be "Anonymous". | |
125 | * Scheduling tasks onto the threadmaster in the 'master' field of the returned | |
126 | * frr_pthread will cause them to run on that pthread. | |
98f14af8 | 127 | * |
a45dc974 | 128 | * @param attr - the thread attributes |
d8a8a8de | 129 | * @param name - Human-readable name |
57019528 | 130 | * @param os_name - 16 characters (including '\0') thread name to set in os, |
98f14af8 QY |
131 | * @return the created frr_pthread upon success, or NULL upon failure |
132 | */ | |
d8a8a8de | 133 | struct frr_pthread *frr_pthread_new(struct frr_pthread_attr *attr, |
57019528 | 134 | const char *name, const char *os_name); |
d8a8a8de QY |
135 | |
136 | /* | |
137 | * Changes the name of the frr_pthread. | |
138 | * | |
139 | * @param fpt - the frr_pthread to operate on | |
140 | * @param name - Human-readable name | |
57019528 CS |
141 | * @param os_name - 16 characters thread name , including the null |
142 | * terminator ('\0') to set in os. | |
143 | * @return - on success returns 0 otherwise nonzero error number. | |
d8a8a8de | 144 | */ |
57019528 CS |
145 | int frr_pthread_set_name(struct frr_pthread *fpt, const char *name, |
146 | const char *os_name); | |
98f14af8 | 147 | |
a45dc974 QY |
148 | /* |
149 | * Destroys an frr_pthread. | |
98f14af8 QY |
150 | * |
151 | * Assumes that the associated pthread, if any, has already terminated. | |
152 | * | |
153 | * @param fpt - the frr_pthread to destroy | |
154 | */ | |
155 | void frr_pthread_destroy(struct frr_pthread *fpt); | |
156 | ||
a45dc974 QY |
157 | /* |
158 | * Gets an existing frr_pthread by its id. | |
98f14af8 QY |
159 | * |
160 | * @return frr_thread associated with the provided id, or NULL on error | |
161 | */ | |
b1087f35 | 162 | struct frr_pthread *frr_pthread_get(uint32_t id); |
98f14af8 | 163 | |
a45dc974 QY |
164 | /* |
165 | * Creates a new pthread and binds it to a frr_pthread. | |
98f14af8 QY |
166 | * |
167 | * This function is a wrapper for pthread_create. The first parameter is the | |
168 | * frr_pthread to bind the created pthread to. All subsequent arguments are | |
a45dc974 QY |
169 | * passed unmodified to pthread_create(). The frr_pthread * provided will be |
170 | * used as the argument to the pthread entry function. If it is necessary to | |
171 | * pass additional data, the 'data' field in the frr_pthread may be used. | |
98f14af8 QY |
172 | * |
173 | * This function returns the same code as pthread_create(). If the value is | |
174 | * zero, the provided frr_pthread is bound to a running POSIX thread. If the | |
175 | * value is less than zero, the provided frr_pthread is guaranteed to be a | |
176 | * clean instance that may be susbsequently passed to frr_pthread_run(). | |
177 | * | |
a45dc974 | 178 | * @param fpt - frr_pthread * to run |
98f14af8 | 179 | * @param attr - see pthread_create(3) |
98f14af8 QY |
180 | * |
181 | * @return see pthread_create(3) | |
182 | */ | |
a45dc974 QY |
183 | int frr_pthread_run(struct frr_pthread *fpt, const pthread_attr_t *attr); |
184 | ||
185 | /* | |
186 | * Waits until the specified pthread has finished setting up and is ready to | |
187 | * begin work. | |
188 | * | |
189 | * If the pthread's code makes use of the startup synchronization mechanism, | |
190 | * this function should be called before attempting to use the functionality | |
191 | * exposed by the pthread. It waits until the 'running' condition is satisfied | |
192 | * (see struct definition of frr_pthread). | |
193 | * | |
194 | * @param fpt - the frr_pthread * to wait on | |
195 | */ | |
196 | void frr_pthread_wait_running(struct frr_pthread *fpt); | |
98f14af8 | 197 | |
a45dc974 QY |
198 | /* |
199 | * Notifies other pthreads that the calling thread has finished setting up and | |
200 | * is ready to begin work. | |
201 | * | |
202 | * This will allow any other pthreads waiting in 'frr_pthread_wait_running' to | |
203 | * proceed. | |
98f14af8 | 204 | * |
a45dc974 QY |
205 | * @param fpt - the frr_pthread * that has finished setting up |
206 | */ | |
207 | void frr_pthread_notify_running(struct frr_pthread *fpt); | |
208 | ||
209 | /* | |
210 | * Stops a frr_pthread with a result. | |
211 | * | |
212 | * @param fpt - frr_pthread * to stop | |
98f14af8 QY |
213 | * @param result - where to store the thread's result, if any. May be NULL if a |
214 | * result is not needed. | |
215 | */ | |
a45dc974 | 216 | int frr_pthread_stop(struct frr_pthread *fpt, void **result); |
98f14af8 QY |
217 | |
218 | /* Stops all frr_pthread's. */ | |
219 | void frr_pthread_stop_all(void); | |
220 | ||
b2140cb7 DS |
221 | /* Yields the current thread of execution */ |
222 | void frr_pthread_yield(void); | |
223 | ||
a45dc974 QY |
224 | /* |
225 | * Returns a unique identifier for use with frr_pthread_new(). | |
98f14af8 QY |
226 | * |
227 | * Internally, this is an integer that increments after each call to this | |
228 | * function. Because the number of pthreads created should never exceed INT_MAX | |
229 | * during the life of the program, there is no overflow protection. If by | |
230 | * chance this function returns an ID which is already in use, | |
231 | * frr_pthread_new() will fail when it is provided. | |
232 | * | |
233 | * @return unique identifier | |
234 | */ | |
d8a8a8de | 235 | uint32_t frr_pthread_get_id(void); |
98f14af8 QY |
236 | |
237 | #endif /* _FRR_PTHREAD_H */ |