source3/lib/server_prefork.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    Common server globals
   4
   5    Copyright (C) Simo Sorce <idra@samba.org> 2011
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  19 */
  20
  21 #include "system/network.h"
  22 #include <tevent.h>
  23 #include "lib/tsocket/tsocket.h"
  24
  25 struct prefork_pool;
  26
  27 enum pf_worker_status {
  28         PF_WORKER_NONE = 0,
  29         PF_WORKER_IDLE,
  30         PF_WORKER_ACCEPTING,
  31         PF_WORKER_BUSY,
  32         PF_WORKER_EXITING
  33 };
  34
  35 enum pf_server_cmds {
  36         PF_SRV_MSG_NONE = 0,
  37         PF_SRV_MSG_EXIT
  38 };
  39
  40 /**
  41 * @brief This structure is shared between the controlling parent and the
  42 *        the child. The parent can only write to the 'cmds' and
  43 *        'allowed_clients' variables, while a child is running.
  44 *        The child can change 'status', and 'num_clients'.
  45 *        All other variables are initialized by the parent before forking the
  46 *        child.
  47 */
  48 struct pf_worker_data {
  49         pid_t pid;
  50         enum pf_worker_status status;
  51         time_t started;
  52         time_t last_used;
  53         int num_clients;
  54
  55         enum pf_server_cmds cmds;
  56         int allowed_clients;
  57 };
  58
  59 /**
  60 * @brief This is the 'main' function called by a child right after the fork.
  61 *        It is daemon specific and should initialize and perform whatever
  62 *        operation the child is meant to do. Returning from this function will
  63 *        cause the termination of the child.
  64 *
  65 * @param ev             The event context
  66 * @param msg_ctx        The messaging context
  67 * @param pf             The mmaped area used to communicate with parent
  68 * @param listen_fd_size The number of file descriptors to monitor
  69 * @param listen_fds     The array of file descriptors
  70 * @param lock_fd        The locking file descriptor
  71 * @param private_data   Private data that needs to be passed to the main
  72 *                       function from the calling parent.
  73 *
  74 * @return Returns the exit status to be reported to the parent via exit()
  75 */
  76 typedef int (prefork_main_fn_t)(struct tevent_context *ev,
  77                                 struct messaging_context *msg_ctx,
  78                                 struct pf_worker_data *pf,
  79                                 int child_id,
  80                                 int listen_fd_size,
  81                                 int *listen_fds,
  82                                 int lock_fd,
  83                                 void *private_data);
  84
  85 /**
  86 * @brief Callback function for parents that also want to be called on sigchld
  87 *
  88 * @param ev_ctx         The event context
  89 * @param pool           The pool handler
  90 * @param private_data   Data private to the parent
  91 */
  92 typedef void (prefork_sigchld_fn_t)(struct tevent_context *ev_ctx,
  93                                     struct prefork_pool *pool,
  94                                     void *private_data);
  95
  96 /* ==== Functions used by controlling process ==== */
  97
  98 /**
  99 * @brief Creates the first pool of preforked processes
 100 *
 101 * @param mem_ctx        The memory context used to hold the pool structure
 102 * @param ev_ctx         The event context
 103 * @param msg_ctx        The messaging context
 104 * @param listen_fd_size The number of file descriptors to monitor
 105 * @param listen_fds     The array of file descriptors to monitor
 106 * @param min_children   Minimum number of children that must be available at
 107 *                       any given time
 108 * @param max_children   Maximum number of children that can be started. Also
 109 *                       determines the initial size of the pool.
 110 * @param main_fn        The children 'main' function to be called after fork
 111 * @param private_data   The children private data.
 112 * @param pf_pool        The allocated pool.
 113 *
 114 * @return True if it was successful, False otherwise.
 115 */
 116 bool prefork_create_pool(TALLOC_CTX *mem_ctx,
 117                          struct tevent_context *ev_ctx,
 118                          struct messaging_context *msg_ctx,
 119                          int listen_fd_size, int *listen_fds,
 120                          int min_children, int max_children,
 121                          prefork_main_fn_t *main_fn, void *private_data,
 122                          struct prefork_pool **pf_pool);
 123 /**
 124 * @brief Function used to attempt to expand the size of children.
 125 *
 126 * @param pfp            The pool structure.
 127 * @param new_max        The new max number of children.
 128 *
 129 * @return 0 if operation was successful
 130 *         ENOSPC if the mmap area could not be grown to the requested size
 131 *         EINVAL if the new max is invalid.
 132 *
 133 * NOTE: this function can easily fail if the mmap area cannot be enlarged.
 134 *       A well behaving parent MUST NOT error out if this happen.
 135 */
 136 int prefork_expand_pool(struct prefork_pool *pfp, int new_max);
 137
 138 /**
 139 * @brief Used to prefork a number of new children
 140 *
 141 * @param ev_ctx         The event context
 142 * @param msg_ctx        The messaging context
 143 * @param pfp            The pool structure
 144 * @param num_children   The number of children to be started
 145 *
 146 * @return The number of new children effectively forked.
 147 *
 148 * NOTE: This method does not expand the pool, if the max number of children
 149 *       has already been forked it will do nothing.
 150 */
 151 int prefork_add_children(struct tevent_context *ev_ctx,
 152                          struct messaging_context *msg_ctx,
 153                          struct prefork_pool *pfp,
 154                          int num_children);
 155 /**
 156 * @brief Commands a number of children to stop and exit
 157 *
 158 * @param pfp            The pool.
 159 * @param num_children   The number of children we need to retire.
 160 * @param age_limit      The minimum age a child has been active to be
 161 *                       considered for retirement. (Compared against the
 162 *                       'started' value in the pf_worker_data structure of the
 163 *                       children.
 164 *
 165 * @return Number of children that were signaled to stop
 166 *
 167 * NOTE: Only children that have no attached clients can be stopped.
 168 *       If all the available children are too young or are busy then it
 169 *       is possible that none will be asked to stop.
 170 */
 171 int prefork_retire_children(struct prefork_pool *pfp,
 172                             int num_children, time_t age_limit);
 173 /**
 174 * @brief Count the number of active children
 175 *
 176 * @param pfp    The pool.
 177 * @param total  Returns the number of children currently alive
 178 *
 179 * @return The number of children actually serving clients
 180 */
 181 int prefork_count_active_children(struct prefork_pool *pfp, int *total);
 182
 183 /**
 184 * @brief Inform all children that they are allowed to accept 'max' clients
 185 *        now. Use this when all children are already busy and more clients
 186 *        are trying to connect. It will allow each child to handle more than
 187 *        one client at a time, up to 'max'.
 188 *
 189 * @param pfp    The pool.
 190 * @param max    Max number of clients per child.
 191 */
 192 void prefork_increase_allowed_clients(struct prefork_pool *pfp, int max);
 193
 194 /**
 195 * @brief Reset the maximum allowd clients per child to 1.
 196 *        Does not reduce the number of clients actually beeing served by
 197 *        any given child, but prevents children from overcommitting from
 198 *        now on.
 199 *
 200 * @param pfp    The pool.
 201 */
 202 void prefork_reset_allowed_clients(struct prefork_pool *pfp);
 203
 204 /**
 205 * @brief Send a specific signal to all children.
 206 *        Used to send SIGHUP when a reload of the configuration is needed
 207 *        for example.
 208 *
 209 * @param pfp            The pool.
 210 * @param signal_num     The signal number to be sent.
 211 */
 212 void prefork_send_signal_to_all(struct prefork_pool *pfp, int signal_num);
 213
 214 /**
 215 * @brief Sets the SIGCHLD callback
 216 *
 217 * @param pfp            The pool handler.
 218 * @param sigchld_fn     The callback function (pass NULL to unset).
 219 * @param private_data   Private data for the callback function.
 220 */
 221 void prefork_set_sigchld_callback(struct prefork_pool *pfp,
 222                                   prefork_sigchld_fn_t *sigchld_fn,
 223                                   void *private_data);
 224
 225 /* ==== Functions used by children ==== */
 226
 227 /**
 228 * @brief Try to listen and accept on one of the listening sockets.
 229 *        Asynchronusly tries to grab the lock and perform an accept.
 230 *        Will automatically update the 'status' of the child and handle
 231 *        all the locking/unlocking/timingout as necessary.
 232 *        Changes behavior depending on whether the child already has other
 233 *        client connections. If not it blocks on the lock call for periods of
 234 *        time. Otherwise it loops on the lock using a timer in order to allow
 235 *        processing of the other clients requests.
 236 *
 237 * @param mem_ctx        The memory context on whic to allocate the request
 238 * @param ev             The event context
 239 * @param pf             The child/parent shared structure
 240 * @param listen_fd_size The number of listening file descriptors
 241 * @param listen_fds     The array of listening file descriptors
 242 * @param lock_fd        The locking file descriptor
 243 *
 244 * @return The tevent request pointer or NULL on allocation errors.
 245 */
 246 struct tevent_req *prefork_listen_send(TALLOC_CTX *mem_ctx,
 247                                         struct tevent_context *ev,
 248                                         struct pf_worker_data *pf,
 249                                         int listen_fd_size,
 250                                         int *listen_fds,
 251                                         int lock_fd);
 252 /**
 253 * @brief Returns the file descriptor after the new client connection has
 254 *        been accepted.
 255 *
 256 * @param req            The request
 257 * @param mem_ctx        The memory context for cli_addr and srv_addr
 258 * @param fd             The new file descriptor.
 259 * @param srv_addr       The server address in tsocket_address format
 260 * @param cli_addr       The client address in tsocket_address format
 261 *
 262 * @return       The error in case the operation failed.
 263 */
 264 int prefork_listen_recv(struct tevent_req *req,
 265                         TALLOC_CTX *mem_ctx, int *fd,
 266                         struct tsocket_address **srv_addr,
 267                         struct tsocket_address **cli_addr);
 268