Global request data

19.0.0 released Nov 08, 2023

Global request data

The purpose of global-request data is to facilitate using global variable(s) within a single request anywhere in your code. This is different from global-process-data which is used across many requests.

You can of course create global variables in C (and use C's "extern" to make them available anywhere). Vely's global-request data is an easier and more structured way to share data globally within a single request, without having to actually define and maintain global variables. It also makes it more maintainable because the usage of shared global information is well-encapsulated and easy to track (for instance in code reviews).

What is global-request data

Global-request data is a generic pointer (void*) that points to any memory you wish to be shared among all your code within a single request. This memory is usually a structure containing information globally pertinent to your application. The pointer's scope is a single request, and it is initialized to NULL before each request. It is stored in Vely's internal request structure so it can be used anywhere.

Setting

set-req data <data>

where <data> is a pointer to any memory you wish to use anywhere in your code.

Getting

Global-request data can be obtained anywhere in your code with:

get-req data to <data>

where <data> is a pointer to any type.

Usage

Typically you would define a structure or a typedef that encapsulates any data that needs to be shared throughout your code during a single request processing.

Then in before-request-handler, you would create the variable (or an array) of this type by using new-mem - this way the memory is automatically released at the end of the request. Use new-mem for any members that need allocating, thus eliminating the possibility of memory leaks. Initialize anything that needs it.

Next, save the pointer to the variable (or an array) you created by using set-req.

Finally, anywhere you need to set or get any data, use get-req to get the pointer and manipulate or read your global-request data.

Examples

Suppose your application has an include file my.h in which you define type "reqdata":

#ifndef _MY
#define _MY

typedef struct s_reqdata {
    bool some_flag;
    bool another_flag;
    char *ptr;
} reqdata;

#endif

Your before-request-handler might look like this - note that my.h is included, providing your type definition "reqdata":

#include "vely.h"
#include "my.h"

void _before () {
    reqdata *rd; // A pointer to global-request data

    // Allocate global-request data
    new-mem rd size sizeof(reqdata)

    // Initialize values in it
    rd->some_flag = false;
    rd->another_flag = false;

    // Save the pointer so you can use it anywhere with get-req
    set-req data rd
}

In the above code, a new pointer "rd" to type "reqdata" is created with new-mem. Data initialization takes place - anything that needs initialization should be initialized. Finally, pointer "rd" is saved to request's internal structure with set-req, so it can be used anywhere during request processing.

In your code, wherever it's needed, you can obtain this data into a local pointer of the same type "reqdata" (in this case pointer name is "mydata"). You can do that with get-req and then examine or set any global variable you wish:

#include "vely.h"
#include "my.h"

void mycode () {

    ...
    reqdata *mydata; // declare local pointer 

    // get the actual value of a pointer, so now it points to global-request data
    get-req data to mydata

    // do whatever you want with the data: examine, set etc.
    if (mydata->another_flag) {
        mydata->some_flag = true;
        my_data->ptr = "some data";
    }
}