manage-memory
Purpose: Turn on/off managed memory.
manage-memory [ on | off | <expression> ]
By default, Vely memory is managed - this means any outstanding memory used by your request will be freed when the request ends (see
memory_handling). You can change this behavior for a time by using manage-memory.
If "on" clause is used, any memory allocated afterwards by any Vely statement is freed automatically (the default behavior). This is managed memory mode.
If "off" clause is used, any memory allocated afterwards by any Vely statement is not freed automatically; this behavior will be in effect until the end of the request or until manage-memory with "on" clause is called. This is unmanaged memory mode.
If boolean <expression> is given, and if it evaluates to true then it's the same as "on" clause; if it evaluates to false then it's the same as "off" clause.
- Freeing, reallocating, using with other C API
If memory is unmanaged, you can use other memory handling statements on such memory (such as
delete-mem or
resize-mem) in unmanaged memory mode only - do not directly use C's free(), realloc() and similar. However, unmanaged memory can be used with any other C API (i.e. libraries); this is useful if you receive already allocated memory from such libraries or need to pass malloc-allocated memory to them.
- Scope
manage-memory has effect in the current request only. Regardless of whether managed or unmanaged memory was used last before the request ended, both the
after_request_handler and the following request will run with the default behavior (i.e. managed). This is true even when your request exits with
exit-request or
report-error.
If you have a
startup_handler, you can use unmanaged memory; once the execution returns from the startup handler, all memory requests will be managed again.
If you have a
before_request_handler or
after_request_handler, you can use unmanaged memory; once the execution returns from either handler, it will be managed again.
- Request data
Note that request-specific variables provided by Vely are always managed internal memory. As such, if you want to use them as unmanaged memory, you must make a copy first (for instance with
copy-string). This includes
input-param,
request-body and
get-req. See below an example to save a request's input parameter as unmanaged memory available to all future requests.
- Using
You may want to store managed memory pointers in
global_process_data in order to be useful across many requests - this is one purpose of unmanaged memory. Another is to use with external C APIs.
Important: using unmanaged memory carries additional responsibilities for the developer, because any such
allocated memory must be explicitly deleted when not needed, or there will be a memory leak. Use it only in special circumstances; its use is generally discouraged otherwise. Such circumstances typically involve data that should survive automatic memory deallocation at the end of the request or with external C API.
Examples
In this example, the input parameter to a very first request issued in a process is copied to variable "var", the value of which then persists for all following requests:
input-param ipar
static char *var = NULL;
if (var == NULL) {
manage-memory off
copy-string ipar to var
manage-memory on
}
p-out var
Create memory and pass it to another API:
manage-memory off
new-mem define var size 1024
call_some_API(&var);
...
delete-mem var
manage-memory on
See also
Memory (
delete-mem manage-memory memory_handling new-mem resize-mem )
SEE ALL (
documentation)