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 #ifndef _SOURCE3_LIB_SERVER_PREFORK_H_
  22 #define _SOURCE3_LIB_SERVER_PREFORK_H_
  23
  24 #include "system/network.h"
  25 #include <tevent.h>
  26 #include "lib/tsocket/tsocket.h"
  27
  28 struct prefork_pool;
  29
  30 enum pf_worker_status {
  31         PF_WORKER_NONE = 0,
  32         PF_WORKER_ALIVE,
  33         PF_WORKER_ACCEPTING,
  34         PF_WORKER_EXITING
  35 };
  36
  37 enum pf_server_cmds {
  38         PF_SRV_MSG_NONE = 0,
  39         PF_SRV_MSG_EXIT
  40 };
  41
  42 /**
  43  * @brief This structure contains a socket listening for clients and a
  44  *        private pointer with any data associated to that particular
  45  *        socket.
  46  */
  47 struct pf_listen_fd {
  48         /* The socket to listen on */
  49         int fd;
  50
  51         /* The socket associated data */
  52         void *fd_data;
  53 };
  54
  55 /**
  56 * @brief This structure is shared between the controlling parent and the
  57 *        the child. The parent can only write to the 'cmds' and
  58 *        'allowed_clients' variables, while a child is running.
  59 *        The child can change 'status', and 'num_clients'.
  60 *        All other variables are initialized by the parent before forking the
  61 *        child.
  62 */
  63 struct pf_worker_data {
  64         pid_t pid;
  65         enum pf_worker_status status;
  66         time_t started;
  67         time_t last_used;
  68         int num_clients;
  69
  70         enum pf_server_cmds cmds;
  71         int allowed_clients;
  72 };
  73
  74 /**
  75 * @brief This is the 'main' function called by a child right after the fork.
  76 *        It is daemon specific and should initialize and perform whatever
  77 *        operation the child is meant to do. Returning from this function will
  78 *        cause the termination of the child.
  79 *
  80 * @param ev             The event context
  81 * @param msg_ctx        The messaging context
  82 * @param pf             The mmaped area used to communicate with parent
  83 * @param listen_fd_size The number of file descriptors to monitor
  84 * @param listen_fds     The array of file descriptors
  85 * @param private_data   Private data that needs to be passed to the main
  86 *                       function from the calling parent.
  87 *
  88 * @return Returns the exit status to be reported to the parent via exit()
  89 */
  90 typedef int (prefork_main_fn_t)(struct tevent_context *ev,
  91                                 struct messaging_context *msg_ctx,
  92                                 struct pf_worker_data *pf,
  93                                 int child_id,
  94                                 int listen_fd_size,
  95                                 struct pf_listen_fd *pf_listen_fds,
  96                                 void *private_data);
  97
  98 /**
  99 * @brief Callback function for parents that also want to be called on sigchld
 100 *
 101 * @param ev_ctx         The event context
 102 * @param pool           The pool handler
 103 * @param private_data   Data private to the parent
 104 */
 105 typedef void (prefork_sigchld_fn_t)(struct tevent_context *ev_ctx,
 106                                     struct prefork_pool *pool,
 107                                     void *private_data);
 108
 109 /* ==== Functions used by controlling process ==== */
 110
 111 /**
 112 * @brief Creates the first pool of preforked processes
 113 *
 114 * @param mem_ctx        The memory context used to hold the pool structure
 115 * @param ev_ctx         The event context
 116 * @param msg_ctx        The messaging context
 117 * @param listen_fd_size The number of file descriptors to monitor
 118 * @param listen_fds     The array of file descriptors to monitor
 119 * @param min_children   Minimum number of children that must be available at
 120 *                       any given time
 121 * @param max_children   Maximum number of children that can be started. Also
 122 *                       determines the initial size of the pool.
 123 * @param main_fn        The children 'main' function to be called after fork
 124 * @param private_data   The children private data.
 125 * @param pf_pool        The allocated pool.
 126 *
 127 * @return True if it was successful, False otherwise.
 128 *
 129 * NOTE: each listen_fd is forced to non-blocking mode once handed over.
 130 * You should not toush listen_fds once you hand the to the prefork library.
 131 */
 132 bool prefork_create_pool(TALLOC_CTX *mem_ctx,
 133                          struct tevent_context *ev_ctx,
 134                          struct messaging_context *msg_ctx,
 135                          int listen_fd_size, struct pf_listen_fd *listen_fds,
 136                          int min_children, int max_children,
 137                          prefork_main_fn_t *main_fn, void *private_data,
 138                          struct prefork_pool **pf_pool);
 139 /**
 140 * @brief Function used to attempt to expand the size of children.
 141 *
 142 * @param pfp            The pool structure.
 143 * @param new_max        The new max number of children.
 144 *
 145 * @return 0 if operation was successful
 146 *         ENOSPC if the mmap area could not be grown to the requested size
 147 *         EINVAL if the new max is invalid.
 148 *
 149 * NOTE: this function can easily fail if the mmap area cannot be enlarged.
 150 *       A well behaving parent MUST NOT error out if this happen.
 151 */
 152 int prefork_expand_pool(struct prefork_pool *pfp, int new_max);
 153
 154 /**
 155 * @brief Used to prefork a number of new children
 156 *
 157 * @param ev_ctx         The event context
 158 * @param msg_ctx        The messaging context
 159 * @param pfp            The pool structure
 160 * @param num_children   The number of children to be started
 161 *
 162 * @return The number of new children effectively forked.
 163 *
 164 * NOTE: This method does not expand the pool, if the max number of children
 165 *       has already been forked it will do nothing.
 166 */
 167 int prefork_add_children(struct tevent_context *ev_ctx,
 168                          struct messaging_context *msg_ctx,
 169                          struct prefork_pool *pfp,
 170                          int num_children);
 171 /**
 172 * @brief Commands a number of children to stop and exit
 173 *
 174 * @param msg_ctx        The messaging context.
 175 * @param pfp            The pool.
 176 * @param num_children   The number of children we need to retire.
 177 * @param age_limit      The minimum age a child has been active to be
 178 *                       considered for retirement. (Compared against the
 179 *                       'started' value in the pf_worker_data structure of the
 180 *                       children.
 181 *
 182 * @return Number of children that were signaled to stop
 183 *
 184 * NOTE: Only children that have no attached clients can be stopped.
 185 *       If all the available children are too young or are busy then it
 186 *       is possible that none will be asked to stop.
 187 */
 188 int prefork_retire_children(struct messaging_context *msg_ctx,
 189                             struct prefork_pool *pfp,
 190                             int num_children, time_t age_limit);
 191 /**
 192 * @brief Count the number of children
 193 *
 194 * @param pfp    The pool.
 195 * @param active Number of children currently active if not NULL
 196 *
 197 * @return The total number of children.
 198 */
 199 int prefork_count_children(struct prefork_pool *pfp, int *active);
 200
 201 /**
 202 * @brief Count the number of actual connections currently allowed
 203 *
 204 * @param pfp            The pool.
 205 *
 206 * @return The number of connections that can still be opened by clients
 207 *         with the current pool of children.
 208 */
 209 int prefork_count_allowed_connections(struct prefork_pool *pfp);
 210
 211 /**
 212 * @brief Increase the amount of clients each child is allowed to handle
 213 *        simultaneaously. It will allow each child to handle more than
 214 *        one client at a time, up to 'max' (currently set to 100).
 215 *
 216 * @param pfp    The pool.
 217 * @param max    Max number of allowed connections per child
 218 */
 219 void prefork_increase_allowed_clients(struct prefork_pool *pfp, int max);
 220
 221 /**
 222 * @brief Decrease the amount of clients each child is allowed to handle.
 223 *        Min is 1.
 224 *
 225 * @param pfp    The pool.
 226 */
 227 void prefork_decrease_allowed_clients(struct prefork_pool *pfp);
 228
 229 /**
 230 * @brief Reset the maximum allowd clients per child to 1.
 231 *        Does not reduce the number of clients actually beeing served by
 232 *        any given child, but prevents children from overcommitting from
 233 *        now on.
 234 *
 235 * @param pfp    The pool.
 236 */
 237 void prefork_reset_allowed_clients(struct prefork_pool *pfp);
 238
 239 /**
 240 * @brief Send a specific signal to all children.
 241 *        Used to send SIGHUP when a reload of the configuration is needed
 242 *        for example.
 243 *
 244 * @param pfp            The pool.
 245 * @param signal_num     The signal number to be sent.
 246 */
 247 void prefork_send_signal_to_all(struct prefork_pool *pfp, int signal_num);
 248
 249 /**
 250 * @brief Send a message to all children that the server changed something
 251 *        in the pool and they may want to take action.
 252 *
 253 * @param msg_ctx        The messaging context.
 254 * @param pfp            The pool.
 255 */
 256 void prefork_warn_active_children(struct messaging_context *msg_ctx,
 257                                   struct prefork_pool *pfp);
 258
 259 /**
 260 * @brief Sets the SIGCHLD callback
 261 *
 262 * @param pfp            The pool handler.
 263 * @param sigchld_fn     The callback function (pass NULL to unset).
 264 * @param private_data   Private data for the callback function.
 265 */
 266 void prefork_set_sigchld_callback(struct prefork_pool *pfp,
 267                                   prefork_sigchld_fn_t *sigchld_fn,
 268                                   void *private_data);
 269
 270 /* ==== Functions used by children ==== */
 271
 272 /**
 273 * @brief Try to listen and accept on one of the listening sockets.
 274 *        Asynchronusly tries to grab the lock and perform an accept.
 275 *        Will automatically update the 'status' of the child and handle
 276 *        all the locking/unlocking/timingout as necessary.
 277 *        Changes behavior depending on whether the child already has other
 278 *        client connections. If not it blocks on the lock call for periods of
 279 *        time. Otherwise it loops on the lock using a timer in order to allow
 280 *        processing of the other clients requests.
 281 *
 282 * @param mem_ctx        The memory context on whic to allocate the request
 283 * @param ev             The event context
 284 * @param pf             The child/parent shared structure
 285 * @param listen_fd_size The number of listening file descriptors
 286 * @param listen_fds     The array of listening file descriptors
 287 *
 288 * @return The tevent request pointer or NULL on allocation errors.
 289 */
 290 struct tevent_req *prefork_listen_send(TALLOC_CTX *mem_ctx,
 291                                         struct tevent_context *ev,
 292                                         struct pf_worker_data *pf,
 293                                         int listen_fd_size,
 294                                         struct pf_listen_fd *listen_fds);
 295 /**
 296 * @brief Returns the file descriptor after the new client connection has
 297 *        been accepted.
 298 *
 299 * @param req            The request
 300 * @param mem_ctx        The memory context for cli_addr and srv_addr
 301 * @param fd             The new file descriptor.
 302 * @param srv_addr       The server address in tsocket_address format
 303 * @param cli_addr       The client address in tsocket_address format
 304 *
 305 * @return       The error in case the operation failed.
 306 */
 307 int prefork_listen_recv(struct tevent_req *req,
 308                         TALLOC_CTX *mem_ctx, int *fd, void **fd_data,
 309                         struct tsocket_address **srv_addr,
 310                         struct tsocket_address **cli_addr);
 311
 312 #endif /* _SOURCE3_LIB_SERVER_PREFORK_H_ */