docs.roxen.comView this page in a printer friendly mode
DocsRoxenWebServer 3.3System Developer ManualIntroduction
Copyright  2004, Roxen Internet Software
Suggestions, comments & compliments

The Inner Workings of Roxen

The Inner Workings of Roxen

In programming Roxen, it is helpful to be aware of how the larger building blocks fit together, what goes where and so on to have a fair grasp of the general layout of the programming environment. This section will rush through Roxen from one end to the other, nothing important and/or useful concepts in the process. Understanding everything along the way is not essential, but having once heard about them does not hurt.

Roxen is a collection of Pike scripts and modules. When firing up the start script, it sets up some essential environment variables to keep dynamic libraries and various other external stuff happy. After a rapid progression of start script argument parsing and setting up paths, it rotates the logs and launches the first Pike script; server/base_server/roxenloader.pike. Standard output and the standard error streams, stderr for short, is redirected to the debug log, unless you launched the start script with the --once parameter, in which case you will see everything in your shell console. We mention this, since it is very handy while developing.

Before racing off the topic of the start script, there is at least one other set of options essential to the developer, namely defines. Hidden all over Roxen to the casual user are some hefty amounts of #ifdef:ed helpful debug code that would swamp the logs if always turned on. To set a define, append -Ddefine_name to the command line, as in -DREQUEST_DEBUG (for some rather verbose information about most things happening with each request as it passes through roxen).

Next in turn, the Roxen loader bootstraps the server, making sure some dependencies are met, setting up some constants not commonly present in Pike and installs Roxen's own Pike master program, server/etc/roxen_master.pike. This program is responsible for, among other things, the dumping and reloading of programs.

Then, the very core of Roxen, server/base_server/roxen.pike gets loaded. For generally speedy loading, Roxen dumps a lot of its components once compiled, to be loaded back instantaneously next time if started with the same set of defines. The configuration of all virtual servers are loaded next, their respective ports get registered and unless the flag --no-delayed-load was passed to the start script, not much more happens next until the first request arrives to a server. This means, of course, this code in a module of yours will not run until a server using the module is needed.

At this stage, the server process is up and about and will listen to incoming requests on all registered ports. When a request to an uninitialized server is received, Roxen will initialize that server, loading and strapping all of its modules. Once done, the request is sent forth through the common processing sequence. Your applications will not be affected by the delayed loading, but nevertheless it is healthy knowing what happens and how. To the application, whether it be a module, a script, an rxml page or a servlet, the delayed loading is transparent and does not interfere with the programming environment.

For the rest of the lifespan of the Roxen process, it will go about its business listening and responding to requests, until terminated with a signal to the process, the start script or by the restart/shutdown administrator action. When the Roxen process receives a SIGHUP signal, it reloads its configuration files. A SIGINT/SIGTERM signal takes down the process and makes the start script spawn off a new one to replace the old one (sending a SIGINT/SIGTERM to the start script shuts down the server without respawning another one).