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
  24 enum pf_worker_status {
  25         PF_WORKER_NONE = 0,
  26         PF_WORKER_IDLE,
  27         PF_WORKER_ACCEPTING,
  28         PF_WORKER_BUSY,
  29         PF_WORKER_EXITING
  30 };
  31
  32 enum pf_server_cmds {
  33         PF_SRV_MSG_NONE = 0,
  34         PF_SRV_MSG_EXIT
  35 };
  36
  37 /**
  38 * @brief This structure is shared betwee the controlling parent and the
  39 *        the child. The parent can only write to the 'cmds' and
  40 *        'allowed_clients' variables, while a child is running.
  41 *        The child can change 'status', and 'num_clients'.
  42 *        All other variables are initialized by the parent before forking the
  43 *        child.
  44 */
  45 struct pf_worker_data {
  46         pid_t pid;
  47         enum pf_worker_status status;
  48         time_t started;
  49         time_t last_used;
  50         int num_clients;
  51
  52         enum pf_server_cmds cmds;
  53         int allowed_clients;
  54 };
  55
  56 /**
  57 * @brief This is the 'main' function called by a child right after the fork.
  58 *        It is daemon specific and should initialize and perform whatever
  59 *        operation the child is meant to do. Returning from this function will
  60 *        cause the termination of the child.
  61 *
  62 * @param ev             The event context
  63 * @param pf             The mmaped area used to communicate with parent
  64 * @param listen_fd_size The number of file descriptors to monitor
  65 * @param listen_fds     The array of file descriptors
  66 * @param lock_fd        The locking file descriptor
  67 * @param private_data   Private data that needs to be passed to the main
  68 *                       function from the calling parent.
  69 *
  70 * @return Returns the exit status to be reported to the parent via exit()
  71 */
  72 typedef int (prefork_main_fn_t)(struct tevent_context *ev,
  73                                 struct pf_worker_data *pf,
  74                                 int listen_fd_size,
  75                                 int *listen_fds,
  76                                 int lock_fd,
  77                                 void *private_data);
  78
  79 struct prefork_pool;
  80
  81
  82 /* ==== Functions used by controlling process ==== */
  83
  84 /**
  85 * @brief Creates the first pool of preforked processes
  86 *
  87 * @param ev_ctx         The event context
  88 * @param mem_ctx        The memory context used to hold the pool structure
  89 * @param listen_fd_size The number of file descriptors to monitor
  90 * @param listen_fds     The array of file descriptors to monitor
  91 * @param min_children   Minimum number of children that must be available at
  92 *                       any given time
  93 * @param max_children   Maximum number of children that can be started. Also
  94 *                       determines the initial size of the pool.
  95 * @param main_fn        The children 'main' function to be called after fork
  96 * @param private_data   The children private data.
  97 * @param pf_pool        The allocated pool.
  98 *
  99 * @return True if it was successful, False otherwise.
 100 */
 101 bool prefork_create_pool(struct tevent_context *ev_ctx, TALLOC_CTX *mem_ctx,
 102                          int listen_fd_size, int *listen_fds,
 103                          int min_children, int max_children,
 104                          prefork_main_fn_t *main_fn, void *private_data,
 105                          struct prefork_pool **pf_pool);
 106 /**
 107 * @brief Function used to attemp to expand the size of children.
 108 *
 109 * @param pfp            The pool structure.
 110 * @param new_max        The new max number of children.
 111 *
 112 * @return 0 if operation was successful
 113 *         ENOSPC if the mmap area could not be grown to the requested size
 114 *         EINVAL if the new max is invalid.
 115 *
 116 * NOTE: this funciton can easily fail if the mmap area cannot be enlarged.
 117 *       A well behaving parent MUST NOT error out if this happen.
 118 */
 119 int prefork_expand_pool(struct prefork_pool *pfp, int new_max);
 120
 121 /**
 122 * @brief Used to prefork a number of new children
 123 *
 124 * @param ev_ctx         The event context
 125 * @param pfp            The pool structure
 126 * @param num_children   The number of children to be started
 127 *
 128 * @return The number of new children effectively forked.
 129 *
 130 * NOTE: This method does not expand the pool, if the max number of children
 131 *       has already been forked it will do nothing.
 132 */
 133 int prefork_add_children(struct tevent_context *ev_ctx,
 134                          struct prefork_pool *pfp,
 135                          int num_children);
 136 /**
 137 * @brief Commands a number fo children to stop and exit
 138 *
 139 * @param pfp            The pool.
 140 * @param num_children   The number of children we need to retire.
 141 * @param age_limit      The minimum age a child has been active to be
 142 *                       considered for retirement. (Compared against the
 143 *                       'started' value in the pf_worker_data structure of the
 144 *                       children.
 145 *
 146 * @return Number of children that were signaled to stop
 147 *
 148 * NOTE: Only children that has no attached clients can be stopped.
 149 *       If all the available children are too young or are busy than it
 150 *       is possible that none will be asked to stop.
 151 */
 152 int prefork_retire_children(struct prefork_pool *pfp,
 153                             int num_children, time_t age_limit);
 154 /**
 155 * @brief Count the number of active children
 156 *
 157 * @param pfp    The pool.
 158 * @param total  Returns the number of children currently alive
 159 *
 160 * @return The number of children actually serving clients
 161 */
 162 int prefork_count_active_children(struct prefork_pool *pfp, int *total);
 163 /**
 164 * @brief Mark a child structure as free, based on the dead child pid.
 165 *        This function is called when the parent gets back notice a child
 166 *        has died through waitpid. It is critical to call this function
 167 *        when children are reaped so that memory slots can be freed.
 168 *
 169 * @param pfp    The pool.
 170 * @param pid    The child pid.
 171 *
 172 * @return True if the slot was clared. False if the pid is not listed.
 173 */
 174 bool prefork_mark_pid_dead(struct prefork_pool *pfp, pid_t pid);
 175
 176 /**
 177 * @brief Inform all children that they are allowed to accept 'max' clients
 178 *        now. Use this when all children are already busy and more clients
 179 *        are trying to connect. It will allow each child to handle more than
 180 *        one client at a time, up to 'max'.
 181 *
 182 * @param pfp    The pool.
 183 * @param max    Max number of clients per child.
 184 */
 185 void prefork_increase_allowed_clients(struct prefork_pool *pfp, int max);
 186
 187 /**
 188 * @brief Reset the maximum allowd clients per child to 1.
 189 *        Does not reduce the number of clients actually beeing served by
 190 *        any given child, but prevents children from overcommitting from
 191 *        now on.
 192 *
 193 * @param pfp    The pool.
 194 */
 195 void prefork_reset_allowed_clients(struct prefork_pool *pfp);
 196
 197 /**
 198 * @brief Send a specific signal to all children.
 199 *        Used to send SIGHUP when a reload of the configuration is needed
 200 *        for example.
 201 *
 202 * @param pfp            The pool.
 203 * @param signal_num     The signal number to be sent.
 204 */
 205 void prefork_send_signal_to_all(struct prefork_pool *pfp, int signal_num);
 206
 207 /* ==== Functions used by children ==== */
 208
 209 /**
 210 * @brief Try to listen and accept on one of the listening sockets.
 211 *        Asynchronusly tries to grab the lock and perform an accept.
 212 *        Will automatically updated the 'status' of the child and handle
 213 *        all the locking/unlocking/timingout as necessary.
 214 *        Changes behavior depending on whether the child already has other
 215 *        client connections. If not it blocks on the lock call for periods of
 216 *        time. Otherwise it loops on the lock using a timer in order to allow
 217 *        processing of the other clients requests.
 218 *
 219 * @param mem_ctx        The memory context on whic to allocate the request
 220 * @param ev             The event context
 221 * @param pf             The child/parent shared structure
 222 * @param listen_fd_size The number of listening file descriptors
 223 * @param listen_fds     The array of listening file descriptors
 224 * @param lock_fd        The locking file descriptor
 225 * @param addr           The structure that will hold the client address on
 226 *                       return
 227 * @param addrlen        The structure length on return.
 228 *
 229 * @return The tevent request pointer or NULL on allocation errors.
 230 */
 231 struct tevent_req *prefork_listen_send(TALLOC_CTX *mem_ctx,
 232                                         struct tevent_context *ev,
 233                                         struct pf_worker_data *pf,
 234                                         int listen_fd_size,
 235                                         int *listen_fds,
 236                                         int lock_fd,
 237                                         struct sockaddr *addr,
 238                                         socklen_t *addrlen);
 239 /**
 240 * @brief Returns the file descriptor after the new client connection has
 241 *        been accepted.
 242 *
 243 * @param req    The request
 244 * @param fd     The new file descriptor.
 245 *
 246 * @return       The error in case the operation failed.
 247 */
 248 int prefork_listen_recv(struct tevent_req *req, int *fd);