b792fb647c90059d6af8b3b58aae99b379ceb193
[strongswan.git] / 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_ @} */