resmgr_handle_tune()

Updated: April 19, 2023

Tune aspects of client fd-to-OCB mapping

Synopsis:

#include <sys/iofunc.h>
#include <sys/resmgr.h>

int resmgr_handle_tune(int min_handles, 
                       int min_clients, 
                       int max_client_handles,
                       int *min_handles_old, 
                       int *min_clients_old, 
                       int *max_client_handles_old);

Arguments:

min_handles
The minimum number of _resmgr_handle_entry structures to retain, or a negative number to leave the minimum unchanged.
min_clients
The minimum number of hash buckets, or a negative number to leave the minimum unchanged.
max_client_handles
The size of each hash bucket, or a negative number to leave the size unchanged.
min_handles_old, min_clients_old, max_client_handles_old
NULL, or a pointer to a location where the function can store the value used by the resource manager layer at the time of the call.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

One of the functions of the resource manager framework is to perform the mapping of client file descriptors to structures local to the resource manager that describe these descriptors. These structures are often Open Control Blocks (OCBs). For details on OCBs, see resmgr_open_bind(). You can use resmgr_handle_tune() to tune certain aspects of this mapping and subsequent lookups of a client's OCBs.

To perform the described mapping, the resource manager framework uses _resmgr_handle_entry structures. The value of min_handles specifies the minimum number of these structures to keep around. If more than this many structures are in use, they may be returned to the heap via free() as they're released.

The resource manager framework also uses one hash bucket per client. The value of min_clients specifies the minimum number of these buckets to keep around. If more than this many clients are communicating with your resource manager, these buckets may be released back to the heap via free() as particular clients close all their file descriptors to your manager.

The value of max_client_handles specifies the size of each of these hash buckets. The maximum number of lookups to find a particular fd-to-OCB mapping is the client's maximum file descriptor divided by max_client_handles, rounded to the nearest integer, or in pseudocode:

ceil( max_fd / max_client_handles )

If this value changes, the new value takes effect for newly connected clients. Existing clients are unaffected.

Note: To avoid allocator thrashing, the resource manager framework always keeps at least eight handles and hash buckets, no matter what minimum values you specify. It also uses a minimum bucket size of 16.

Returns:

0

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler No
Thread Yes