root/include/crm/common/mainloop.h

/* */

INCLUDED FROM

   1 /*
   2  * Copyright 2009-2025 the Pacemaker project contributors
   3  *
   4  * The version control history for this file may have further details.
   5  *
   6  * This source code is licensed under the GNU Lesser General Public License
   7  * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
   8  */
   9 
  10 #ifndef PCMK__CRM_COMMON_MAINLOOP__H
  11 #define PCMK__CRM_COMMON_MAINLOOP__H
  12 
  13 #include <stdbool.h>    // bool
  14 #include <signal.h>     // sighandler_t
  15 #include <sys/types.h>  // pid_t, ssize_t
  16 
  17 #include <glib.h>       // gpointer, gboolean, guint, GSourceFunc, GMainLoop
  18 #include <qb/qbipcs.h>  // qb_ipcs_service_t, etc.
  19 
  20 #include <crm/common/ipc.h>
  21 
  22 
  23 #ifdef __cplusplus
  24 extern "C" {
  25 #endif
  26 
  27 /**
  28  * \file
  29  * \brief Wrappers for and extensions to glib mainloop
  30  * \ingroup core
  31  */
  32 
  33 enum mainloop_child_flags {
  34     /* don't kill pid group on timeout, only kill the pid */
  35     mainloop_leave_pid_group = 0x01,
  36 };
  37 
  38 // NOTE: sbd (as of at least 1.5.2) uses this
  39 typedef struct trigger_s crm_trigger_t;
  40 
  41 typedef struct mainloop_io_s mainloop_io_t;
  42 typedef struct mainloop_child_s mainloop_child_t;
  43 
  44 // NOTE: sbd (as of at least 1.5.2) uses this
  45 typedef struct mainloop_timer_s mainloop_timer_t;
  46 
  47 void mainloop_cleanup(void);
  48 
  49 // NOTE: sbd (as of at least 1.5.2) uses this
  50 crm_trigger_t *mainloop_add_trigger(int priority, int (*dispatch) (gpointer user_data),
  51                                     gpointer userdata);
  52 
  53 // NOTE: sbd (as of at least 1.5.2) uses this
  54 void mainloop_set_trigger(crm_trigger_t * source);
  55 
  56 void mainloop_trigger_complete(crm_trigger_t * trig);
  57 
  58 gboolean mainloop_destroy_trigger(crm_trigger_t * source);
  59 
  60 #ifndef HAVE_SIGHANDLER_T
  61 typedef void (*sighandler_t)(int);
  62 #endif
  63 
  64 sighandler_t crm_signal_handler(int sig, sighandler_t dispatch);
  65 
  66 // NOTE: sbd (as of at least 1.5.2) uses this
  67 gboolean mainloop_add_signal(int sig, void (*dispatch) (int sig));
  68 
  69 gboolean mainloop_destroy_signal(int sig);
  70 
  71 bool mainloop_timer_running(mainloop_timer_t *t);
  72 
  73 // NOTE: sbd (as of at least 1.5.2) uses this
  74 void mainloop_timer_start(mainloop_timer_t *t);
  75 
  76 // NOTE: sbd (as of at least 1.5.2) uses this
  77 void mainloop_timer_stop(mainloop_timer_t *t);
  78 
  79 guint mainloop_timer_set_period(mainloop_timer_t *t, guint period_ms);
  80 
  81 // NOTE: sbd (as of at least 1.5.2) uses this
  82 mainloop_timer_t *mainloop_timer_add(const char *name, guint period_ms, bool repeat, GSourceFunc cb, void *userdata);
  83 
  84 void mainloop_timer_del(mainloop_timer_t *t);
  85 
  86 struct ipc_client_callbacks {
  87     /*!
  88      * \brief Dispatch function for an IPC connection used as mainloop source
  89      *
  90      * \param[in] buffer    Message read from IPC connection
  91      * \param[in] length    Number of bytes in \p buffer
  92      * \param[in] userdata  User data passed when creating mainloop source
  93      *
  94      * \return Negative value to remove source, anything else to keep it
  95      */
  96     int (*dispatch) (const char *buffer, ssize_t length, gpointer userdata);
  97 
  98     /*!
  99      * \brief Destroy function for mainloop IPC connection client data
 100      *
 101      * \param[in,out] userdata  User data passed when creating mainloop source
 102      */
 103     void (*destroy) (gpointer userdata);
 104 };
 105 
 106 qb_ipcs_service_t *mainloop_add_ipc_server(const char *name, enum qb_ipc_type type,
 107                                            struct qb_ipcs_service_handlers *callbacks);
 108 
 109 /*!
 110  * \brief Start server-side API end-point, hooked into the internal event loop
 111  *
 112  * \param[in] name    name of the IPC end-point ("address" for the client)
 113  * \param[in] type    selects libqb's IPC back-end (or use #QB_IPC_NATIVE)
 114  * \param[in] callbacks  defines libqb's IPC service-level handlers
 115  * \param[in] priority  priority relative to other events handled in the
 116  *                      abstract handling loop, use #QB_LOOP_MED when unsure
 117  *
 118  * \return libqb's opaque handle to the created service abstraction
 119  *
 120  * \note For portability concerns, do not use this function if you keep
 121  *       \p priority as #QB_LOOP_MED, stick with #mainloop_add_ipc_server
 122  *       (with exactly such semantics) instead (once you link with this new
 123  *       symbol employed, you can't downgrade the library freely anymore).
 124  *
 125  * \note The intended effect will only get fully reflected when run-time
 126  *       linked to patched libqb: https://github.com/ClusterLabs/libqb/pull/352
 127  */
 128 qb_ipcs_service_t *mainloop_add_ipc_server_with_prio(const char *name,
 129                                                     enum qb_ipc_type type,
 130                                                     struct qb_ipcs_service_handlers *callbacks,
 131                                                     enum qb_loop_priority prio);
 132 
 133 void mainloop_del_ipc_server(qb_ipcs_service_t * server);
 134 
 135 // @COMPAT max_size parameter is deprecated and unused since 3.0.1
 136 mainloop_io_t *mainloop_add_ipc_client(const char *name, int priority, size_t max_size,
 137                                        void *userdata, struct ipc_client_callbacks *callbacks);
 138 
 139 void mainloop_del_ipc_client(mainloop_io_t * client);
 140 
 141 crm_ipc_t *mainloop_get_ipc_client(mainloop_io_t * client);
 142 
 143 struct mainloop_fd_callbacks {
 144     /*!
 145      * \brief Dispatch function for mainloop file descriptor with data ready
 146      *
 147      * \param[in,out] userdata  User data passed when creating mainloop source
 148      *
 149      * \return Negative value to remove source, anything else to keep it
 150      */
 151     int (*dispatch) (gpointer userdata);
 152 
 153     /*!
 154      * \brief Destroy function for mainloop file descriptor client data
 155      *
 156      * \param[in,out] userdata  User data passed when creating mainloop source
 157      */
 158     void (*destroy) (gpointer userdata);
 159 };
 160 
 161 mainloop_io_t *mainloop_add_fd(const char *name, int priority, int fd, void *userdata,
 162                                struct mainloop_fd_callbacks *callbacks);
 163 
 164 void mainloop_del_fd(mainloop_io_t * client);
 165 
 166 /*
 167  * Create a new tracked process
 168  * To track a process group, use -pid
 169  */
 170 void mainloop_child_add(pid_t pid,
 171                         int timeout,
 172                         const char *desc,
 173                         void *userdata,
 174                         void (*callback) (mainloop_child_t * p, pid_t pid, int core, int signo, int exitcode));
 175 
 176 void mainloop_child_add_with_flags(pid_t pid,
 177                         int timeout,
 178                         const char *desc,
 179                         void *userdata,
 180                         enum mainloop_child_flags,
 181                         void (*callback) (mainloop_child_t * p, pid_t pid, int core, int signo, int exitcode));
 182 
 183 void *mainloop_child_userdata(mainloop_child_t * child);
 184 int mainloop_child_timeout(mainloop_child_t * child);
 185 const char *mainloop_child_name(mainloop_child_t * child);
 186 
 187 pid_t mainloop_child_pid(mainloop_child_t * child);
 188 void mainloop_clear_child_userdata(mainloop_child_t * child);
 189 gboolean mainloop_child_kill(pid_t pid);
 190 
 191 void pcmk_quit_main_loop(GMainLoop *mloop, unsigned int n);
 192 void pcmk_drain_main_loop(GMainLoop *mloop, guint timer_ms,
 193                           bool (*check)(guint));
 194 
 195 #define G_PRIORITY_MEDIUM (G_PRIORITY_HIGH/2)
 196 
 197 #ifdef __cplusplus
 198 }
 199 #endif
 200 
 201 #endif

/* */