lib/frr_pthread.h

   1 /*
   2  * Utilities and interfaces for managing POSIX threads within FRR.
   3  * Copyright (C) 2017  Cumulus Networks, Inc.
   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
  18  */
  19
  20 #ifndef _FRR_PTHREAD_H
  21 #define _FRR_PTHREAD_H
  22
  23 #include <pthread.h>
  24 #include "frratomic.h"
  25 #include "memory.h"
  26 #include "thread.h"
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 #define OS_THREAD_NAMELEN 16
  33
  34 struct frr_pthread;
  35 struct frr_pthread_attr;
  36
  37 struct frr_pthread_attr {
  38         void *(*start)(void *);
  39         int (*stop)(struct frr_pthread *, void **);
  40 };
  41
  42 struct frr_pthread {
  43
  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
  50         /* pthread id */
  51         pthread_t thread;
  52
  53         /* thread master for this pthread's thread.c event loop */
  54         struct thread_master *master;
  55
  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.
  83          *
  84          * Requires: mtx
  85          */
  86         void *data;
  87
  88         /*
  89          * Human-readable thread name.
  90          *
  91          * Requires: mtx
  92          */
  93         char *name;
  94
  95         /* Used in pthread_set_name max 16 characters */
  96         char os_name[OS_THREAD_NAMELEN];
  97 };
  98
  99 extern struct frr_pthread_attr frr_pthread_attr_default;
 100
 101 /*
 102  * Initializes this module.
 103  *
 104  * Must be called before using any of the other functions.
 105  */
 106 void frr_pthread_init(void);
 107
 108 /*
 109  * Uninitializes this module.
 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
 118 /*
 119  * Creates a new frr_pthread with the given attributes.
 120  *
 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.
 127  *
 128  * @param attr - the thread attributes
 129  * @param name - Human-readable name
 130  * @param os_name - 16 characters (including '\0') thread name to set in os,
 131  * @return the created frr_pthread upon success, or NULL upon failure
 132  */
 133 struct frr_pthread *frr_pthread_new(struct frr_pthread_attr *attr,
 134                                     const char *name, const char *os_name);
 135
 136 /*
 137  * Changes the name of the frr_pthread as reported by the operating
 138  * system.
 139  *
 140  * @param fpt - the frr_pthread to operate on
 141  * @return -  on success returns 0 otherwise nonzero error number.
 142  */
 143 int frr_pthread_set_name(struct frr_pthread *fpt);
 144
 145 /*
 146  * Destroys an frr_pthread.
 147  *
 148  * Assumes that the associated pthread, if any, has already terminated.
 149  *
 150  * @param fpt - the frr_pthread to destroy
 151  */
 152 void frr_pthread_destroy(struct frr_pthread *fpt);
 153
 154 /*
 155  * Creates a new pthread and binds it to a frr_pthread.
 156  *
 157  * This function is a wrapper for pthread_create. The first parameter is the
 158  * frr_pthread to bind the created pthread to. All subsequent arguments are
 159  * passed unmodified to pthread_create(). The frr_pthread * provided will be
 160  * used as the argument to the pthread entry function. If it is necessary to
 161  * pass additional data, the 'data' field in the frr_pthread may be used.
 162  *
 163  * This function returns the same code as pthread_create(). If the value is
 164  * zero, the provided frr_pthread is bound to a running POSIX thread. If the
 165  * value is less than zero, the provided frr_pthread is guaranteed to be a
 166  * clean instance that may be susbsequently passed to frr_pthread_run().
 167  *
 168  * @param fpt - frr_pthread * to run
 169  * @param attr - see pthread_create(3)
 170  *
 171  * @return see pthread_create(3)
 172  */
 173 int frr_pthread_run(struct frr_pthread *fpt, const pthread_attr_t *attr);
 174
 175 /*
 176  * Waits until the specified pthread has finished setting up and is ready to
 177  * begin work.
 178  *
 179  * If the pthread's code makes use of the startup synchronization mechanism,
 180  * this function should be called before attempting to use the functionality
 181  * exposed by the pthread. It waits until the 'running' condition is satisfied
 182  * (see struct definition of frr_pthread).
 183  *
 184  * @param fpt - the frr_pthread * to wait on
 185  */
 186 void frr_pthread_wait_running(struct frr_pthread *fpt);
 187
 188 /*
 189  * Notifies other pthreads that the calling thread has finished setting up and
 190  * is ready to begin work.
 191  *
 192  * This will allow any other pthreads waiting in 'frr_pthread_wait_running' to
 193  * proceed.
 194  *
 195  * @param fpt - the frr_pthread * that has finished setting up
 196  */
 197 void frr_pthread_notify_running(struct frr_pthread *fpt);
 198
 199 /*
 200  * Stops a frr_pthread with a result.
 201  *
 202  * @param fpt - frr_pthread * to stop
 203  * @param result - where to store the thread's result, if any. May be NULL if a
 204  * result is not needed.
 205  */
 206 int frr_pthread_stop(struct frr_pthread *fpt, void **result);
 207
 208 /* Stops all frr_pthread's. */
 209 void frr_pthread_stop_all(void);
 210
 211 #ifndef HAVE_PTHREAD_CONDATTR_SETCLOCK
 212 #define pthread_condattr_setclock(A, B)
 213 #endif
 214
 215 #ifdef __cplusplus
 216 }
 217 #endif
 218
 219 #endif /* _FRR_PTHREAD_H */