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