src/libfast/dispatcher.h

   1 /*
   2  * Copyright (C) 2007 Martin Willi
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the
   7  * Free Software Foundation; either version 2 of the License, or (at your
   8  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
   9  *
  10  * This program is distributed in the hope that it will be useful, but
  11  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  12  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  13  * for more details.
  14  */
  15
  16 /**
  17  * @defgroup libfast libfast
  18  * @{
  19  * FastCGI Application Server w/ templates.
  20  *
  21  * Libfast is a framework to write web applications in an MVC fashion. It uses
  22  * the ClearSilver template engine and communicates through FastCGI with
  23  * the webserver. It is multithreaded and really fast.
  24  *
  25  * The application has a global context and a session context. The global
  26  * context is accessed from all sessions simultaneously and therefore
  27  * needs to be threadsave. Often a database wrapper is the global context.
  28  * The session context is instanciated per session. Sessions are managed
  29  * automatically through session cookies. The session context is kept alive
  30  * until the session times out. It must implement the context_t interface and
  31  * a #context_constructor_t is needed to create instances. To each session,
  32  * a set of controllers gets instanciated. The controller instances are per
  33  * session, so you can hold private data for each user.
  34  * Controllers need to implement the controller_t interface and need a
  35  * #controller_constructor_t function to create instances.
  36  *
  37  * A small example shows how to set up libfast:
  38  * @code
  39         dispatcher_t *dispatcher;
  40         your_global_context_implementation_t *global;
  41
  42         global = initialize_your_global_context();
  43
  44         dispatcher = dispatcher_create(NULL, FALSE, 180,
  45                         (context_constructor_t)your_session_context_create, global);
  46         dispatcher->add_controller(dispatcher, your_controller1_create, param1);
  47         dispatcher->add_controller(dispatcher, your_controller2_create, param2);
  48
  49         dispatcher->run(dispatcher, 20);
  50
  51         dispatcher->waitsignal(dispatcher);
  52
  53         dispatcher->destroy(dispatcher);
  54         global->destroy();
  55    @endcode
  56  * @}
  57  *
  58  * @defgroup dispatcher dispatcher
  59  * @{ @ingroup libfast
  60  */
  61
  62 #ifndef DISPATCHER_H_
  63 #define DISPATCHER_H_
  64
  65 #include "controller.h"
  66 #include "filter.h"
  67
  68 typedef struct dispatcher_t dispatcher_t;
  69
  70 /**
  71  * Dispatcher, accepts connections using multiple threads.
  72  *
  73  * The dispatcher creates a session for each client (using SID cookies). In
  74  * each session, a session context is created using the context constructor.
  75  * Each controller is instanciated in the session using the controller
  76  * constructor added with add_controller.
  77  */
  78 struct dispatcher_t {
  79
  80         /**
  81          * Register a controller to the dispatcher.
  82          *
  83          * The first controller added serves as default controller. Client's
  84          * get redirected to it if no other controller matches.
  85          *
  86          * @param constructor   constructor function to the conntroller
  87          * @param param                 param to pass to constructor
  88          */
  89         void (*add_controller)(dispatcher_t *this,
  90                                                    controller_constructor_t constructor, void *param);
  91
  92         /**
  93          * @brief Add a filter to the dispatcher.
  94          *
  95          * @param constructor   constructor to create filter in session
  96          * @param param                 param to pass to constructor
  97          */
  98         void (*add_filter)(dispatcher_t *this,
  99                                            filter_constructor_t constructor, void *param);
 100
 101         /**
 102          * Start with dispatching.
 103          *
 104          * Instanciate a constant thread pool and start dispatching requests.
 105          *
 106          * @param threads               number of dispatching threads
 107          */
 108         void (*run)(dispatcher_t *this, int threads);
 109
 110         /**
 111          * Wait for a relevant signal action.
 112          *
 113          */
 114         void (*waitsignal)(dispatcher_t *this);
 115
 116         /**
 117          * Destroy the dispatcher_t.
 118          */
 119         void (*destroy) (dispatcher_t *this);
 120 };
 121
 122 /**
 123  * Create a dispatcher.
 124  *
 125  * The context constructor is invoked to create a session context for
 126  * each session.
 127  *
 128  * @param socket                FastCGI socket path, NULL for dynamic
 129  * @param debug                 no stripping, no compression, timing information
 130  * @param timeout               session timeout
 131  * @param constructor   construction function for session context
 132  * @param param                 parameter to supply to context constructor
 133  */
 134 dispatcher_t *dispatcher_create(char *socket, bool debug, int timeout,
 135                                                                 context_constructor_t constructor, void *param);
 136
 137 #endif /** DISPATCHER_H_ @}*/