granicus.if.org Git - apache/blob - modules/http2/h2_mplx.h

   1 /* Licensed to the Apache Software Foundation (ASF) under one or more
   2  * contributor license agreements.  See the NOTICE file distributed with
   3  * this work for additional information regarding copyright ownership.
   4  * The ASF licenses this file to You under the Apache License, Version 2.0
   5  * (the "License"); you may not use this file except in compliance with
   6  * the License.  You may obtain a copy of the License at
   7  *
   8  *     http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __mod_h2__h2_mplx__
  18 #define __mod_h2__h2_mplx__
  19
  20 /**
  21  * The stream multiplexer. It pushes buckets from the connection
  22  * thread to the stream threads and vice versa. It's thread-safe
  23  * to use.
  24  *
  25  * There is one h2_mplx instance for each h2_session, which sits on top
  26  * of a particular httpd conn_rec. Input goes from the connection to
  27  * the stream tasks. Output goes from the stream tasks to the connection,
  28  * e.g. the client.
  29  *
  30  * For each stream, there can be at most "H2StreamMaxMemSize" output bytes
  31  * queued in the multiplexer. If a task thread tries to write more
  32  * data, it is blocked until space becomes available.
  33  *
  34  * Writing input is never blocked. In order to use flow control on the input,
  35  * the mplx can be polled for input data consumption.
  36  */
  37
  38 struct apr_pool_t;
  39 struct apr_thread_mutex_t;
  40 struct apr_thread_cond_t;
  41 struct h2_bucket_beam;
  42 struct h2_config;
  43 struct h2_ihash_t;
  44 struct h2_task;
  45 struct h2_stream;
  46 struct h2_request;
  47 struct apr_thread_cond_t;
  48 struct h2_workers;
  49 struct h2_iqueue;
  50
  51 #include <apr_queue.h>
  52
  53 typedef struct h2_mplx h2_mplx;
  54
  55 struct h2_mplx {
  56     long id;
  57     conn_rec *c;
  58     apr_pool_t *pool;
  59     server_rec *s;                  /* server for master conn */
  60
  61     unsigned int event_pending;
  62     unsigned int aborted;
  63     unsigned int is_registered;     /* is registered at h2_workers */
  64
  65     struct h2_ihash_t *streams;     /* all streams currently processing */
  66     struct h2_ihash_t *sredo;       /* all streams that need to be re-started */
  67     struct h2_ihash_t *shold;       /* all streams done with task ongoing */
  68     struct h2_ihash_t *spurge;      /* all streams done, ready for destroy */
  69
  70     struct h2_iqueue *q;            /* all stream ids that need to be started */
  71     struct h2_ififo *readyq;        /* all stream ids ready for output */
  72
  73     struct h2_ihash_t *redo_tasks;  /* all tasks that need to be redone */
  74
  75     int max_streams;        /* max # of concurrent streams */
  76     int max_stream_started; /* highest stream id that started processing */
  77     int tasks_active;       /* # of tasks being processed from this mplx */
  78     int limit_active;       /* current limit on active tasks, dynamic */
  79     int max_active;         /* max, hard limit # of active tasks in a process */
  80     apr_time_t last_idle_block;      /* last time, this mplx entered IDLE while
  81                                       * streams were ready */
  82     apr_time_t last_limit_change;    /* last time, worker limit changed */
  83     apr_interval_time_t limit_change_interval;
  84
  85     apr_thread_mutex_t *lock;
  86     struct apr_thread_cond_t *added_output;
  87     struct apr_thread_cond_t *join_wait;
  88
  89     apr_size_t stream_max_mem;
  90
  91     apr_pool_t *spare_io_pool;
  92     apr_array_header_t *spare_slaves; /* spare slave connections */
  93
  94     struct h2_workers *workers;
  95 };
  96
  97
  98
  99 /*******************************************************************************
 100  * Object lifecycle and information.
 101  ******************************************************************************/
 102
 103 apr_status_t h2_mplx_child_init(apr_pool_t *pool, server_rec *s);
 104
 105 /**
 106  * Create the multiplexer for the given HTTP2 session.
 107  * Implicitly has reference count 1.
 108  */
 109 h2_mplx *h2_mplx_create(conn_rec *c, server_rec *s, apr_pool_t *master,
 110                         struct h2_workers *workers);
 111
 112 /**
 113  * Decreases the reference counter of this mplx and waits for it
 114  * to reached 0, destroy the mplx afterwards.
 115  * This is to be called from the thread that created the mplx in
 116  * the first place.
 117  * @param m the mplx to be released and destroyed
 118  * @param wait condition var to wait on for ref counter == 0
 119  */
 120 void h2_mplx_release_and_join(h2_mplx *m, struct apr_thread_cond_t *wait);
 121
 122 apr_status_t h2_mplx_pop_task(h2_mplx *m, struct h2_task **ptask);
 123
 124 void h2_mplx_task_done(h2_mplx *m, struct h2_task *task, struct h2_task **ptask);
 125
 126 /**
 127  * Shut down the multiplexer gracefully. Will no longer schedule new streams
 128  * but let the ongoing ones finish normally.
 129  * @return the highest stream id being/been processed
 130  */
 131 int h2_mplx_shutdown(h2_mplx *m);
 132
 133 int h2_mplx_is_busy(h2_mplx *m);
 134
 135 /*******************************************************************************
 136  * IO lifetime of streams.
 137  ******************************************************************************/
 138
 139 /**
 140  * Register a stream with the multiplexer. This transfers responisibility
 141  * for lifetime and final destruction to mplx.
 142
 143  * @param mplx the multiplexer
 144  * @param stream the h2 stream instance
 145  */
 146 void h2_mplx_stream_register(h2_mplx *mplx, struct h2_stream *stream);
 147
 148 /**
 149  * Lookup a stream by its id. Will only return active streams, not discarded ones.
 150  * @param mplx the multiplexer
 151  * @param id the stream identifier
 152  * @return the stream or NULL
 153  */
 154 struct h2_stream *h2_mplx_stream_get(h2_mplx *mplx, int id);
 155
 156 /**
 157  * Notifies mplx that a stream has been completely handled on the main
 158  * connection and is ready for cleanup.
 159  *
 160  * @param m the mplx itself
 161  * @param stream the stream ready for cleanup
 162  */
 163 apr_status_t h2_mplx_stream_discard(h2_mplx *m, int stream_id);
 164
 165 /**
 166  * Waits on output data from any stream in this session to become available.
 167  * Returns APR_TIMEUP if no data arrived in the given time.
 168  */
 169 apr_status_t h2_mplx_out_trywait(h2_mplx *m, apr_interval_time_t timeout,
 170                                  struct apr_thread_cond_t *iowait);
 171
 172 apr_status_t h2_mplx_keep_active(h2_mplx *m, struct h2_stream *stream);
 173
 174 /*******************************************************************************
 175  * Stream processing.
 176  ******************************************************************************/
 177
 178 /**
 179  * Process a stream request.
 180  *
 181  * @param m the multiplexer
 182  * @param stream_id the identifier of the stream
 183  * @param r the request to be processed
 184  * @param cmp the stream priority compare function
 185  * @param ctx context data for the compare function
 186  */
 187 apr_status_t h2_mplx_process(h2_mplx *m, int stream_id, h2_stream_pri_cmp *cmp, void *ctx);
 188
 189 /**
 190  * Stream priorities have changed, reschedule pending requests.
 191  *
 192  * @param m the multiplexer
 193  * @param cmp the stream priority compare function
 194  * @param ctx context data for the compare function
 195  */
 196 apr_status_t h2_mplx_reprioritize(h2_mplx *m, h2_stream_pri_cmp *cmp, void *ctx);
 197
 198 typedef apr_status_t stream_ev_callback(void *ctx, struct h2_stream *stream);
 199
 200 /**
 201  * Check if the multiplexer has events for the master connection pending.
 202  * @return != 0 iff there are events pending
 203  */
 204 int h2_mplx_has_master_events(h2_mplx *m);
 205
 206 /**
 207  * Dispatch events for the master connection, such as
 208  ± @param m the multiplexer
 209  * @param on_resume new output data has arrived for a suspended stream
 210  * @param ctx user supplied argument to invocation.
 211  */
 212 apr_status_t h2_mplx_dispatch_master_events(h2_mplx *m,
 213                                             stream_ev_callback *on_resume,
 214                                             void *ctx);
 215
 216 int h2_mplx_awaits_data(h2_mplx *m);
 217
 218 typedef int h2_mplx_stream_cb(struct h2_stream *s, void *ctx);
 219
 220 apr_status_t h2_mplx_stream_do(h2_mplx *m, h2_mplx_stream_cb *cb, void *ctx);
 221
 222 /*******************************************************************************
 223  * Output handling of streams.
 224  ******************************************************************************/
 225
 226 /**
 227  * Opens the output for the given stream with the specified response.
 228  */
 229 apr_status_t h2_mplx_out_open(h2_mplx *mplx, int stream_id,
 230                               struct h2_bucket_beam *beam);
 231
 232 /*******************************************************************************
 233  * h2_mplx list Manipulation.
 234  ******************************************************************************/
 235
 236 /**
 237  * The magic pointer value that indicates the head of a h2_mplx list
 238  * @param  b The mplx list
 239  * @return The magic pointer value
 240  */
 241 #define H2_MPLX_LIST_SENTINEL(b)        APR_RING_SENTINEL((b), h2_mplx, link)
 242
 243 /**
 244  * Determine if the mplx list is empty
 245  * @param b The list to check
 246  * @return true or false
 247  */
 248 #define H2_MPLX_LIST_EMPTY(b)   APR_RING_EMPTY((b), h2_mplx, link)
 249
 250 /**
 251  * Return the first mplx in a list
 252  * @param b The list to query
 253  * @return The first mplx in the list
 254  */
 255 #define H2_MPLX_LIST_FIRST(b)   APR_RING_FIRST(b)
 256
 257 /**
 258  * Return the last mplx in a list
 259  * @param b The list to query
 260  * @return The last mplx int he list
 261  */
 262 #define H2_MPLX_LIST_LAST(b)    APR_RING_LAST(b)
 263
 264 /**
 265  * Insert a single mplx at the front of a list
 266  * @param b The list to add to
 267  * @param e The mplx to insert
 268  */
 269 #define H2_MPLX_LIST_INSERT_HEAD(b, e) do {                             \
 270 h2_mplx *ap__b = (e);                                        \
 271 APR_RING_INSERT_HEAD((b), ap__b, h2_mplx, link);        \
 272 } while (0)
 273
 274 /**
 275  * Insert a single mplx at the end of a list
 276  * @param b The list to add to
 277  * @param e The mplx to insert
 278  */
 279 #define H2_MPLX_LIST_INSERT_TAIL(b, e) do {                             \
 280 h2_mplx *ap__b = (e);                                   \
 281 APR_RING_INSERT_TAIL((b), ap__b, h2_mplx, link);        \
 282 } while (0)
 283
 284 /**
 285  * Get the next mplx in the list
 286  * @param e The current mplx
 287  * @return The next mplx
 288  */
 289 #define H2_MPLX_NEXT(e) APR_RING_NEXT((e), link)
 290 /**
 291  * Get the previous mplx in the list
 292  * @param e The current mplx
 293  * @return The previous mplx
 294  */
 295 #define H2_MPLX_PREV(e) APR_RING_PREV((e), link)
 296
 297 /**
 298  * Remove a mplx from its list
 299  * @param e The mplx to remove
 300  */
 301 #define H2_MPLX_REMOVE(e)       APR_RING_REMOVE((e), link)
 302
 303 /*******************************************************************************
 304  * h2_mplx DoS protection
 305  ******************************************************************************/
 306
 307 /**
 308  * Master connection has entered idle mode.
 309  * @param m the mplx instance of the master connection
 310  * @return != SUCCESS iff connection should be terminated
 311  */
 312 apr_status_t h2_mplx_idle(h2_mplx *m);
 313
 314 #endif /* defined(__mod_h2__h2_mplx__) */