The Shrinker API

OSv provides a simple callback-based API for notifying your application of memory pressure. It's simple to use, and can save your administrators a lot of time over configuring memory usage settings manually.

The memory-hog project is a simple example of a C application that uses the shrinker API. It's available from: https://github.com/dmarti/memory-hog

A C++ example is the osv-memcached project: https://github.com/cloudius-systems/osv/wiki/osv-memcached

NOTE: Shrinker API is available on OSv since version 0.08.

Using the shrinker interface

For people building applications in tandem with the OSv source code, one should include the header <osv/shrinker.h>. That header can be included for both C and C++ applications.

To use the shrinker, C++ users can just create a class that inherits from memory::shrinker and implement the method request_memory. An example is as follows:

class my_shrinker : public memory::shrinker {
public:
   explicit my_shrinker() : memory::shrinker("Example Shrinker") {}
   size_t request_memory(size_t target, bool hard);
};

The method request_memory will be called when for any reason there is shortage of memory in the system. The parameter "target" tells the application how much memory OSv expects it to free. The bigger the target, the more pressure there is in the system. The method request_memory should return the amount of memory actually freed by the shrinker.

In most invocations, the parameter "hard" will be set by OSv as "false". This indicates that the system is acting preemptively, and pressure is starting to build up. The application is free to defer the freeing of objects to a later stage. Having this method called with "hard" set to true, however, means that OSv is under severe memory pressure, and may be unable to serve allocations. If not enough memory is freed, the system may be forced to abort.

The request_memory method is allowed to allocate memory, even in hard shrinks. There is an emergency pool destined for such allocations, but it is not big and is shared among all users of the shrinker interface. Although possible, allocating new memory during request_memory is strongly discouraged.

C applications

For C applications, or C++ applications that are built without access to OSv headers, registering a shrinker involves calling the following function:

void *osv_register_shrinker(const char *name,
                           size_t (*func)(size_t target, bool hard));

An application in C can just do:

extern void *osv_register_shrinker(const char *, size_t (*)(size_t, bool));

int main () {
 ...
 osv_register_shrinker("Example Shrinker", shrinker_function);
 ...
 return 0;
}