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  * $Id$
  16  */
  17
  18 /**
  19  * @defgroup libfast libfast
  20  * @{
  21  * FastCGI Application Server w/ templates.
  22  *
  23  * Libfast is a framework to write web applications in an MVC fashion. It uses
  24  * the ClearSilver template engine and communicates through FastCGI with
  25  * the webserver. It is multithreaded and really fast.
  26  *
  27  * The application has a global context and a session context. The global
  28  * context is accessed from all sessions simultaneously and therefore
  29  * needs to be threadsave. Often a database wrapper is the global context.
  30  * The session context is instanciated per session. Sessions are managed
  31  * automatically through session cookies. The session context is kept alive
  32  * until the session times out. It must implement the context_t interface and
  33  * a #context_constructor_t is needed to create instances. To each session,
  34  * a set of controllers gets instanciated. The controller instances are per
  35  * session, so you can hold private data for each user.
  36  * Controllers need to implement the controller_t interface and need a
  37  * #controller_constructor_t function to create instances.
  38  *
  39  * A small example shows how to set up libfast:
  40  * @code
  41         dispatcher_t *dispatcher;
  42         your_global_context_implementation_t *global;
  43
  44         global = initialize_your_global_context();
  45
  46         dispatcher = dispatcher_create(NULL, FALSE, 180,
  47                         (context_constructor_t)your_session_context_create, global);
  48         dispatcher->add_controller(dispatcher, your_controller1_create, param1);
  49         dispatcher->add_controller(dispatcher, your_controller2_create, param2);
  50
  51         dispatcher->run(dispatcher, 20);
  52
  53         dispatcher->waitsignal(dispatcher);
  54
  55         dispatcher->destroy(dispatcher);
  56         global->destroy();
  57    @endcode
  58  * @}
  59  *
  60  * @defgroup dispatcher dispatcher
  61  * @{ @ingroup libfast
  62  */
  63
  64 #ifndef DISPATCHER_H_
  65 #define DISPATCHER_H_
  66
  67 #include "controller.h"
  68 #include "filter.h"
  69
  70 typedef struct dispatcher_t dispatcher_t;
  71
  72 /**
  73  * Dispatcher, accepts connections using multiple threads.
  74  *
  75  * The dispatcher creates a session for each client (using SID cookies). In
  76  * each session, a session context is created using the context constructor.
  77  * Each controller is instanciated in the session using the controller
  78  * constructor added with add_controller.
  79  */
  80 struct dispatcher_t {
  81
  82         /**
  83          * Register a controller to the dispatcher.
  84          *
  85          * The first controller added serves as default controller. Client's
  86          * get redirected to it if no other controller matches.
  87          *
  88          * @param constructor   constructor function to the conntroller
  89          * @param param                 param to pass to constructor
  90          */
  91         void (*add_controller)(dispatcher_t *this,
  92                                                    controller_constructor_t constructor, void *param);
  93
  94         /**
  95          * @brief Add a filter to the dispatcher.
  96          *
  97          * @param constructor   constructor to create filter in session
  98          * @param param                 param to pass to constructor
  99          */
 100         void (*add_filter)(dispatcher_t *this,
 101                                            filter_constructor_t constructor, void *param);
 102
 103         /**
 104          * Start with dispatching.
 105          *
 106          * Instanciate a constant thread pool and start dispatching requests.
 107          *
 108          * @param threads               number of dispatching threads
 109          */
 110         void (*run)(dispatcher_t *this, int threads);
 111
 112         /**
 113          * Wait for a relevant signal action.
 114          *
 115          */
 116         void (*waitsignal)(dispatcher_t *this);
 117
 118         /**
 119          * Destroy the dispatcher_t.
 120          */
 121         void (*destroy) (dispatcher_t *this);
 122 };
 123
 124 /**
 125  * Create a dispatcher.
 126  *
 127  * The context constructor is invoked to create a session context for
 128  * each session.
 129  *
 130  * @param socket                FastCGI socket path, NULL for dynamic
 131  * @param debug                 no stripping, no compression, timing information
 132  * @param timeout               session timeout
 133  * @param constructor   construction function for session context
 134  * @param param                 parameter to supply to context constructor
 135  */
 136 dispatcher_t *dispatcher_create(char *socket, bool debug, int timeout,
 137                                                                 context_constructor_t constructor, void *param);
 138
 139 #endif /** DISPATCHER_H_ @}*/