Vely logo Empower C
install  tutorials  examples
documentation  license  about

12.1.0 released on Sep 19, 2022

Global request data



DESCRIPTION:


The purpose of global request data is to facilitate using global variable(s) anywhere in your code.

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, 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. 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 to 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";
    }
}


SEE ALSO:


Requests ( after_request_handler   before_request_handler   global_request_data   input-param   non_request   request   startup_handler   url-param   vely_dispatch_request  )  SEE ALL (documentation)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Icons copyright PaweĊ‚ Kuna licensed under MIT. This web page is licensed under CC-BY-SA-4.0.