Memory handling

18.4.0 released Sep 25, 2023

Memory handling

Managed and unmanaged

Memory allocated by Vely statements (and internally by Vely) can be managed or unmanaged. By default it's managed and it might be the only kind you use.

Managed memory used by Vely statements is tracked and always fully freed at the end of a request, even if you don't do it. In fact that is preferrable in most cases (more on this below). This is the default behavior. In this case, your program is in "managed memory mode".

Unmanaged memory is rarely used; more on it further down.

Allocated memory

Some Vely statements allocate memory for their results. Each statement's documentation specifies the clause(s) that allocate memory. Those that have not been so specified do not allocate memory. If memory cannot be allocated, your request will error out (see error-handling); this does not affect other requests.

Managed memory

All such memory is automatically freed at the end of each request, so in general you may not need to free memory at all. If needed, you can free memory with delete-mem or reallocate with resize-mem, or use statements that explicitly do that (such as delete-query for instance). However, unless your program uses lots of memory for longer, it may make sense to not do that and let Vely release it at the end of the request. The reasons for this are:

releasing memory programmatically is in some cases error prone and may lead to malfunctions and crashes,
releasing memory programmatically in some cases prolongs the duration of the request, making some of the allocated memory stay so for longer. Having requests of shorter duration and releasing memory all at once at the end may be preferable.

In the end, it is up to you whether to release memory explicitly, let Vely do it, or a bit of both.

Managed memory is freed even if it is no longer accessible to the program, thus preventing memory leaks; this is important for stability of long-running processes.

Note that managed memory is not the same as "garbage collector", which can consume considerable resources. Vely's managed memory is very light because it only tracks memory used by Vely statements and such memory is simply released at the end of a request; there is nothing more to it - no scanning of the heap, tracking of objects, counting references, compacting memory etc. Hence "managed memory" is managed so lightly to have virtually no impact on performance.

Internal process memory

Memory needed for cross-request purposes, such as prepared database statements or process configuration data, is kept for the life of the process.

Memory reuse

Any of the Vely statement-APIs that return allocated memory will always create it new. In other words, the previously allocated memory will not be reused by default.

This is so that common and hard-to-track bugs relating to memory reuse, proper sizing and re-allocation can be avoided, such as passing non-Vely allocated pointers, bad pointers or memory of insufficient allocation. In addition, this approach may increase performance because allocating memory is generally faster than reallocating; given requests are short and frequent by nature, it means increased productivity and performance.

Either way, you can always explicitly reuse memory during request processing by freeing previously allocated memory of any statement that does so, see delete-mem or any other specialized statement (such as delete-query or delete-json for example).

Open file descriptors

Any files opened by open-file statement are automatically closed by Vely at the end of the request. This enhances stability of long-running server processes because Linux system by default offers only about 1000 open files to a process. A bug can quickly exhaust this pool and cause a malfunction or a crash - Vely prevents this by closing any such open files when the request ends. Note that this is true whether your program is currently in managed or unmanaged memory mode.

Unmanaged memory

Unmanaged memory is not tracked and you have to manually free it. It uses the same allocation as standard C's malloc() memory. Memory allocated is unmanaged when "off" clause is used in manage-memory - this is "unmanaged memory mode". Unmanaged memory is used only in special circumstances and in general should not be used without a good reason. See global-process-data.

Memory allocated in managed mode can only be freed or reallocated while in managed mode. And conversely, memory allocated in unmanaged mode can only be freed or reallocated while in unmanaged mode. Attempting otherwise will cause your program to error out.

By default, memory usage is managed. Use manage-memory with "off" clause to enter unmanaged mode, and "on" clause to revert to managed mode. Here is an example of unmanaged memory mode:

// Enter unmanaged mode
manage-memory off
new-mem var size 1024
// Exit managed mode
manage-memory on

If you are using unmanaged memory, then you must explicitly manage it by using delete-mem or resize-mem, or use statements that explicitly do that (such as delete-query for instance) - these operations must be performed in unmanaged memory mode as well.