Vely dispatch request

19.0.0 released Nov 08, 2023

Request handling

An incoming request is handled by a first available process:

For a command-line application, there is only a single process, and it handles a single requests before it exits.
For a server application (see FastCGI), there can be any number of processes running. A process is chosen to service a request if it is currently not serving other requests; this way there are no processes waiting idle unnecessarily. Each process is identical and can serve any request, i.e. it has all request handlers available to it. Thus, when a process is chosen to serve a request, then this process will simply execute a function that handles a request.

Processing a request

To handle a request, a process first calls "vely_dispatch_request()" function.

"void vely_dispatch_request()" is an automatically generated request-dispatching function in Vely. It uses request name (see request-URL) to call the appropriate request handler.

For example, if the request name is "myreq", then function with signature "void myreq()" will be called - such function must be implemented in "myreq.vely" source code file.

You can implement two hooks into vely_dispatch_request(): one that executes before each request handling (before-request-handler) and one that executes afterwards (after-request-handler).

At the end of the request, all request memory and all file handles allocated by Vely will be freed (see memory-handling).

You cannot change the implementation of vely_dispatch_request(), but you can see it in the build directory (see vv).

Performance

Vely uses a hash table to match a request with a handler function. Typically, it takes only close to a single lookup to find the handler function, regardless of the number of possible request names a process may serve (be it 10 or 10,000 different request names). Vely pre-generates a hash table at compile time, so no run-time cycles are spent on creating it. Also, the hash table is created as a continuous block of memory in the program's data segment, which loads as a part of the program (likely as a single memory copy) and is very fast because accessing the data will likely need no pointer translations. As a result, Vely dispatcher is extremely fast.

Unrecognized requests

If no request has been recognized (i.e. request name does not match any request-handling .vely source file), then

no request handler will execute,
before-request-handler and after-request-handler will not execute either,
and a "Request not found" error will be reported via report-error.

Debugging

In a debugger, breaking in this function gives you a good starting point to debug the handling of any given request, for instance in gdb:

br vely_dispatch_request