lib/frr_pthread.h

   1 /*
   2  * Utilities and interfaces for managing POSIX threads
   3  * Copyright (C) 2017  Cumulus Networks
   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 "memory.h"
  25 #include "thread.h"
  26
  27 DECLARE_MTYPE(PTHREAD_PRIM);
  28
  29 struct frr_pthread {
  30
  31         /* pthread id */
  32         pthread_t thread;
  33
  34         /* frr thread identifier */
  35         unsigned int id;
  36
  37         /* thread master for this pthread's thread.c event loop */
  38         struct thread_master *master;
  39
  40         /* start routine */
  41         void *(*start_routine)(void *);
  42
  43         /* stop routine */
  44         int (*stop_routine)(void **, struct frr_pthread *);
  45
  46         /* the (hopefully descriptive) name of this thread */
  47         char *name;
  48 };
  49
  50 /* Initializes this module.
  51  *
  52  * Must be called before using any of the other functions.
  53  */
  54 void frr_pthread_init(void);
  55
  56 /* Uninitializes this module.
  57  *
  58  * Destroys all registered frr_pthread's and internal data structures.
  59  *
  60  * It is safe to call frr_pthread_init() after this function to reinitialize
  61  * the module.
  62  */
  63 void frr_pthread_finish(void);
  64
  65 /* Creates a new frr_pthread.
  66  *
  67  * If the provided ID is already assigned to an existing frr_pthread, the
  68  * return value will be NULL.
  69  *
  70  * @param name - the name of the thread. Doesn't have to be unique, but it
  71  * probably should be. This value is copied and may be safely free'd upon
  72  * return.
  73  *
  74  * @param id - the integral ID of the thread. MUST be unique. The caller may
  75  * use this id to retrieve the thread.
  76  *
  77  * @param start_routine - start routine for the pthread, will be passed to
  78  * pthread_create (see those docs for details)
  79  *
  80  * @param stop_routine - stop routine for the pthread, called to terminate the
  81  * thread. This function should gracefully stop the pthread and clean up any
  82  * thread-specific resources. The passed pointer is used to return a data
  83  * result.
  84  *
  85  * @return the created frr_pthread upon success, or NULL upon failure
  86  */
  87 struct frr_pthread *frr_pthread_new(const char *name, unsigned int id,
  88                                     void *(*start_routine)(void *),
  89                                     int (*stop_routine)(void **,
  90                                                         struct frr_pthread *));
  91
  92 /* Destroys an frr_pthread.
  93  *
  94  * Assumes that the associated pthread, if any, has already terminated.
  95  *
  96  * @param fpt - the frr_pthread to destroy
  97  */
  98 void frr_pthread_destroy(struct frr_pthread *fpt);
  99
 100 /* Gets an existing frr_pthread by its id.
 101  *
 102  * @return frr_thread associated with the provided id, or NULL on error
 103  */
 104 struct frr_pthread *frr_pthread_get(unsigned int id);
 105
 106 /* Creates a new pthread and binds it to a frr_pthread.
 107  *
 108  * This function is a wrapper for pthread_create. The first parameter is the
 109  * frr_pthread to bind the created pthread to. All subsequent arguments are
 110  * passed unmodified to pthread_create().
 111  *
 112  * This function returns the same code as pthread_create(). If the value is
 113  * zero, the provided frr_pthread is bound to a running POSIX thread. If the
 114  * value is less than zero, the provided frr_pthread is guaranteed to be a
 115  * clean instance that may be susbsequently passed to frr_pthread_run().
 116  *
 117  * @param id - frr_pthread to bind the created pthread to
 118  * @param attr - see pthread_create(3)
 119  * @param arg - see pthread_create(3)
 120  *
 121  * @return see pthread_create(3)
 122  */
 123 int frr_pthread_run(unsigned int id, const pthread_attr_t *attr, void *arg);
 124
 125 /* Stops an frr_pthread with a result.
 126  *
 127  * @param id - frr_pthread to stop
 128  * @param result - where to store the thread's result, if any. May be NULL if a
 129  * result is not needed.
 130  */
 131 int frr_pthread_stop(unsigned int id, void **result);
 132
 133 /* Stops all frr_pthread's. */
 134 void frr_pthread_stop_all(void);
 135
 136 /* Yields the current thread of execution */
 137 void frr_pthread_yield(void);
 138
 139 /* Returns a unique identifier for use with frr_pthread_new().
 140  *
 141  * Internally, this is an integer that increments after each call to this
 142  * function. Because the number of pthreads created should never exceed INT_MAX
 143  * during the life of the program, there is no overflow protection. If by
 144  * chance this function returns an ID which is already in use,
 145  * frr_pthread_new() will fail when it is provided.
 146  *
 147  * @return unique identifier
 148  */
 149 unsigned int frr_pthread_get_id(void);
 150
 151 #endif /* _FRR_PTHREAD_H */