dlb.h

Date:Fri Jul 15 2022

NAME

dlb.h

SYNOPSIS


#include 'dlb_types.h'
#include 'dlb_errors.h'

Functions

int DLB_Init (int ncpus, const_dlb_cpu_set_t mask, const char *dlb_args)
Initialize DLB library and all its internal data structures. Must be called once and only once by each process in the DLB system.
int DLB_Finalize (void)
Finalize DLB library and clean up all its data structures. Must be called by each process before exiting the system.
int DLB_PreInit (const_dlb_cpu_set_t mask, char ***next_environ)
Pre-Initialize process.
int DLB_Enable (void)
Enable DLB and all its features in case it was previously disabled, otherwise it has no effect.
int DLB_Disable (void)
Disable DLB actions for the calling process.
int DLB_SetMaxParallelism (int max)
Set the maximum number of resources to be used by the calling process.
int DLB_UnsetMaxParallelism (void)
Unset the maximum number of resources to be used by the calling process.
int DLB_CallbackSet (dlb_callbacks_t which, dlb_callback_t callback, void *arg)
Setter for DLB callbacks.
int DLB_CallbackGet (dlb_callbacks_t which, dlb_callback_t *callback, void **arg)
Getter for DLB callbacks.
int DLB_Lend (void)
Lend all the current CPUs.
int DLB_LendCpu (int cpuid)
Lend a specific CPU.
int DLB_LendCpus (int ncpus)
Lend a specific amount of CPUs, only useful for systems that do not work with cpu masks.
int DLB_LendCpuMask (const_dlb_cpu_set_t mask)
Lend a set of CPUs.
int DLB_Reclaim (void)
Reclaim all the CPUs that are owned by the process.
int DLB_ReclaimCpu (int cpuid)
Reclaim a specific CPU that are owned by the process.
int DLB_ReclaimCpus (int ncpus)
Reclaim a specific amount of CPUs that are owned by the process.
int DLB_ReclaimCpuMask (const_dlb_cpu_set_t mask)
Reclaim a set of CPUs.
int DLB_AcquireCpu (int cpuid)
Acquire a specific CPU.
int DLB_AcquireCpus (int ncpus)
Acquire a specific amount of CPUs.
int DLB_AcquireCpuMask (const_dlb_cpu_set_t mask)
Acquire a set of CPUs.
int DLB_AcquireCpusInMask (int ncpus, const_dlb_cpu_set_t mask)
Acquire some CPUs from a subset of CPUs.
int DLB_Borrow (void)
Borrow all the possible CPUs registered on DLB.
int DLB_BorrowCpu (int cpuid)
Borrow a specific CPU.
int DLB_BorrowCpus (int ncpus)
Borrow a specific amount of CPUs.
int DLB_BorrowCpuMask (const_dlb_cpu_set_t mask)
Borrow a set of CPUs.
int DLB_BorrowCpusInMask (int ncpus, const_dlb_cpu_set_t mask)
Borrow some CPUs from a subset of CPUs.
int DLB_Return (void)
Return claimed CPUs of other processes.
int DLB_ReturnCpu (int cpuid)
Return the specific CPU if it has been reclaimed.
int DLB_ReturnCpuMask (const_dlb_cpu_set_t mask)
Return a set of CPUs if some of them have been reclaimed.
int DLB_PollDROM (int *ncpus, dlb_cpu_set_t mask)
Poll DROM module to check if the process needs to adapt to a new mask or number of CPUs.
int DLB_PollDROM_Update (void)
Poll DROM module to check if the process needs to adapt to a new mask and update it if necessary using the registered callbacks.
int DLB_CheckCpuAvailability (int cpuid)
Check whether the specified CPU is being used by another process.
int DLB_Barrier (void)
Barrier between processes in the node.
int DLB_BarrierAttach (void)
Attach process to the DLB_Barrier team.
int DLB_BarrierDetach (void)
Barrier between processes in the node.
int DLB_SetVariable (const char *variable, const char *value)
Change the value of a DLB internal variable.
int DLB_GetVariable (const char *variable, char *value)
Query the value of a DLB internal variable.
int DLB_PrintVariables (int print_extended)
Print DLB internal variables.
int DLB_PrintShmem (int num_columns, dlb_printshmem_flags_t print_flags)
Print the data stored in the shmem.
const char * DLB_Strerror (int errnum)
Obtain a pointer to a string that describes the error code passed by argument.
int DLB_AutoSizerStart (void)
API call to adjust the resources of an application.
int DLB_AutoSizerEnd (void)
API call to adjust the resources of an application.

Function Documentation

int DLB_Init (int ncpus, const_dlb_cpu_set_t mask, const char * dlb_args)

Initialize DLB library and all its internal data structures. Must be called once and only once by each process in the DLB system.

Parameters:

ncpus optional, initial number of CPUs, or 0
mask optional, initial CPU mask to register, or NULL
dlb_args optional parameter to overwrite DLB_ARGS options, or NULL

Returns:

DLB_SUCCESS on success

DLB_ERR_INIT if DLB is already initialized

DLB_ERR_PERM if DLB cannot register the mask passed by argument

DLB_ERR_NOMEM if DLB cannot allocate more processes

Parameters ncpus and mask are used to register CPUs owned by the calling process into the system. DLB advanced usage requires mask information so it is recommended to provide a CPU mask, but DLB also accepts an integer in case the program does not have the mask affinity details. Parameter dlb_args can be used in conjunction with DLB_ARGS, the former takes precedence in case of conflicting options.

int DLB_Finalize (void)

Finalize DLB library and clean up all its data structures. Must be called by each process before exiting the system.

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

int DLB_PreInit (const_dlb_cpu_set_t mask, char *** next_environ)

Pre-Initialize process.

Parameters:

mask initial CPU mask to register
next_environ environment to modify if the process is going to fork-exec

Returns:

DLB_SUCCESS on success

DLB_ERR_PERM if DLB cannot register the mask passed by argument

DLB_ERR_NOMEM if DLB cannot allocate more processes

int DLB_Enable (void)

Enable DLB and all its features in case it was previously disabled, otherwise it has no effect.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if DLB is already enabled

DLB_ERR_NOINIT if DLB is not initialized

It can be used in conjunction with DLB_Disable() to delimit sections of the code where DLB calls will not have effect.

int DLB_Disable (void)

Disable DLB actions for the calling process.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if DLB is already disabled

DLB_ERR_NOINIT if DLB is not initialized

This call resets the original resources for the process and returns any external CPU it may be using at that time. While DLB is disabled there will not be any resource sharing for this process.

int DLB_SetMaxParallelism (int max)

Set the maximum number of resources to be used by the calling process.

Parameters:

max max number of CPUs

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

Used to delimit sections of the code that the developer knows that only a maximum number of CPUs can benefit the execution. If a process reaches its maximum number of resources used at any time, subsequent calls to borrow CPUs will be ignored until some of them are returned. If the maximum number of CPUs exceeds the current number of assigned CPUs at the time of this function call, DLB will readjust as needed.

int DLB_UnsetMaxParallelism (void)

Unset the maximum number of resources to be used by the calling process.

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

Unset the maximum number of CPUs previously assigned to this process. Subsequent calls to borrow will not be delimited by this parameter.

int DLB_CallbackSet (dlb_callbacks_t which, dlb_callback_t callback, void * arg)

Setter for DLB callbacks.

Parameters:

which callback type
callback function pointer to register
arg opaque argument to pass in each callback invocation

Returns:

DLB_SUCCESS on success

DLB_ERR_NOCBK if the callback type does not exist

Register a new callback for the callback type which. The callback type comes predefined by the enum values of dlb_callbacks_t. It is highly recommended to register at least callbacks for dlb_callback_enable_cpu and dlb_callback_disable_cpu.

int DLB_CallbackGet (dlb_callbacks_t which, dlb_callback_t * callback, void ** arg)

Getter for DLB callbacks.

Parameters:

which callback type
callback registered callback function for the specified callback type
arg opaque argument to pass in each callback invocation

Returns:

DLB_SUCCESS on success

DLB_ERR_NOCBK if the callback type does not exist

Obtain the previously registered callback and arg for the specified which callback type.

int DLB_Lend (void)

Lend all the current CPUs.

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Lend CPUs of the process to the system. A lent CPU may be assigned to other process that demands more resources. If the CPU was originally owned by the process it may be reclaimed.

int DLB_LendCpu (int cpuid)

Lend a specific CPU.

Parameters:

cpuid CPU id to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Lend CPUs of the process to the system. A lent CPU may be assigned to other process that demands more resources. If the CPU was originally owned by the process it may be reclaimed.

int DLB_LendCpus (int ncpus)

Lend a specific amount of CPUs, only useful for systems that do not work with cpu masks.

Parameters:

ncpus number of CPUs to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Lend CPUs of the process to the system. A lent CPU may be assigned to other process that demands more resources. If the CPU was originally owned by the process it may be reclaimed.

int DLB_LendCpuMask (const_dlb_cpu_set_t mask)

Lend a set of CPUs.

Parameters:

mask CPU mask to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Lend CPUs of the process to the system. A lent CPU may be assigned to other process that demands more resources. If the CPU was originally owned by the process it may be reclaimed.

int DLB_Reclaim (void)

Reclaim all the CPUs that are owned by the process.

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if there is no CPUs to reclaim

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Reclaim CPUs that were previously lent. It is mandatory that the CPUs belong to the calling process.

int DLB_ReclaimCpu (int cpuid)

Reclaim a specific CPU that are owned by the process.

Parameters:

cpuid CPU id to reclaim

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if there is no CPUs to reclaim

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be reclaimed

Reclaim CPUs that were previously lent. It is mandatory that the CPUs belong to the calling process.

int DLB_ReclaimCpus (int ncpus)

Reclaim a specific amount of CPUs that are owned by the process.

Parameters:

ncpus Number of CPUs to reclaim

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if there is no CPUs to reclaim

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Reclaim CPUs that were previously lent. It is mandatory that the CPUs belong to the calling process.

int DLB_ReclaimCpuMask (const_dlb_cpu_set_t mask)

Reclaim a set of CPUs.

Parameters:

mask CPU mask to reclaim

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if there is no CPUs to reclaim

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be reclaimed

Reclaim CPUs that were previously lent. It is mandatory that the CPUs belong to the calling process.

int DLB_AcquireCpu (int cpuid)

Acquire a specific CPU.

Parameters:

cpuid CPU to acquire

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if the CPU is already acquired

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be acquired

DLB_ERR_REQST if there are too many requests for this resource

Acquire CPUs from the system. If the CPU belongs to the process the call is equivalent to a reclaim action. Otherwise the process attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpus (int ncpus)

Acquire a specific amount of CPUs.

Parameters:

ncpus Number of CPUs to acquire

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if cannot acquire any CPU

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_REQST if there are too many requests for this resource

Acquire CPUs from the system. If the CPU belongs to the process the call is equivalent to a reclaim action. Otherwise the process attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpuMask (const_dlb_cpu_set_t mask)

Acquire a set of CPUs.

Parameters:

mask CPU set to acquire

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if cannot acquire any CPU

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be acquired

DLB_ERR_REQST if there are too many requests for these resources

Acquire CPUs from the system. If the CPU belongs to the process the call is equivalent to a reclaim action. Otherwise the process attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpusInMask (int ncpus, const_dlb_cpu_set_t mask)

Acquire some CPUs from a subset of CPUs.

Parameters:

ncpus Number of CPUs to acquire
mask CPU set to acquire from

Returns:

DLB_SUCCESS on success

DLB_NOTED if the petition cannot be immediately fulfilled

DLB_NOUPDT if cannot acquire any CPU

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be acquired

DLB_ERR_REQST if there are too many requests for these resources

Acquire CPUs from the system. If the CPU belongs to the process the call is equivalent to a reclaim action. Otherwise the process attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_Borrow (void)

Borrow all the possible CPUs registered on DLB.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if cannot borrow any resources

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Borrow CPUs from the system only if they are idle. No other action is done if the CPU is not available.

int DLB_BorrowCpu (int cpuid)

Borrow a specific CPU.

Parameters:

cpuid cpu CPU to borrow

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if CPU cannot borrowed

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Borrow CPUs from the system only if they are idle. No other action is done if the CPU is not available.

int DLB_BorrowCpus (int ncpus)

Borrow a specific amount of CPUs.

Parameters:

ncpus Number of CPUs to borrow

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if cannot borrow any resources

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Borrow CPUs from the system only if they are idle. No other action is done if the CPU is not available.

int DLB_BorrowCpuMask (const_dlb_cpu_set_t mask)

Borrow a set of CPUs.

Parameters:

mask CPU set to borrow

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if cannot borrow any resources

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Borrow CPUs from the system only if they are idle. No other action is done if the CPU is not available.

int DLB_BorrowCpusInMask (int ncpus, const_dlb_cpu_set_t mask)

Borrow some CPUs from a subset of CPUs.

Parameters:

ncpus Number of CPUs to borrow
mask CPU set to borrow from

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if cannot borrow any resources

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

Borrow CPUs from the system only if they are idle. No other action is done if the CPU is not available.

int DLB_Return (void)

Return claimed CPUs of other processes.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if no need to return

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be returned

Return CPUs to the system commonly triggered by a reclaim action from other process but stating that the current process still demands the usage of these CPUs. This action will enqueue a request for when the resources are available again. If the caller does not want to keep the resource after receiving a reclaim, the correct action is lend.

int DLB_ReturnCpu (int cpuid)

Return the specific CPU if it has been reclaimed.

Parameters:

cpuid CPU to return

Returns:

DLB_SUCCESS on success

DLB_ERR_NOINIT if DLB is not initialized

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be returned

Return CPUs to the system commonly triggered by a reclaim action from other process but stating that the current process still demands the usage of these CPUs. This action will enqueue a request for when the resources are available again. If the caller does not want to keep the resource after receiving a reclaim, the correct action is lend.

int DLB_ReturnCpuMask (const_dlb_cpu_set_t mask)

Return a set of CPUs if some of them have been reclaimed.

Parameters:

mask CPU set to return

Returns:

DLB_SUCCESS on success

DLB_ERR_DISBLD if DLB is disabled

DLB_ERR_PERM if the resources cannot be returned

Return CPUs to the system commonly triggered by a reclaim action from other process but stating that the current process still demands the usage of these CPUs. This action will enqueue a request for when the resources are available again. If the caller does not want to keep the resource after receiving a reclaim, the correct action is lend.

int DLB_PollDROM (int * ncpus, dlb_cpu_set_t mask)

Poll DROM module to check if the process needs to adapt to a new mask or number of CPUs.

Parameters:

ncpus optional, variable to receive the new number of CPUs
mask optional, variable to receive the new mask

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if no update id needed

DLB_ERR_NOCOMP if DROM is not enabled (option –drom)

If DROM is enabled and the interaction mode is not asynchronous, this function can be called to poll the status of the CPU ownership.

int DLB_PollDROM_Update (void)

Poll DROM module to check if the process needs to adapt to a new mask and update it if necessary using the registered callbacks.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if no update id needed

DLB_ERR_NOCOMP if DROM is not enabled (option –drom)

Same as DLB_PollDROM(), but calling the registered callbacks to update the ownership info instead of returning the data by argument.

int DLB_CheckCpuAvailability (int cpuid)

Check whether the specified CPU is being used by another process.

Parameters:

cpuid CPU to be checked

Returns:

DLB_SUCCESS if the CPU is available

DLB_NOTED if the CPU is owned but still guested by other process

DLB_NOUPDT if the CPU is owned but still not reclaimed

DLB_ERR_PERM if the CPU cannot be acquired or has been disabled

DLB_ERR_DISBLD if DLB is disabled

int DLB_Barrier (void)

Barrier between processes in the node.

Returns:

DLB_SUCCESS on success

DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)

int DLB_BarrierAttach (void)

Attach process to the DLB_Barrier team.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if process was already attached

DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)

If the process had previusly called DLB_BarrierDetach, this function allows a process to become part again of the DLB_Barrier team. Otherwise it has no effect.

int DLB_BarrierDetach (void)

Barrier between processes in the node.

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if process was already detached

DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)

Remove process from the DLB_Barrier team. The process will no longer be able to call DLB_Barrier. Other processes in the team will not synchronize with this process on their respective calls to DLB_Barrier.

int DLB_SetVariable (const char * variable, const char * value)

Change the value of a DLB internal variable.

Parameters:

variable Internal variable to set
value New value

Returns:

DLB_SUCCESS on success

DLB_ERR_PERM if the variable is readonly

DLB_ERR_NOENT if the variable does not exist

Set a DLB internal variable. These variables are the same ones specified in DLB_ARGS, although not all of them can be modified at runtime. If the variable is readonly the setter function will return an error.

int DLB_GetVariable (const char * variable, char * value)

Query the value of a DLB internal variable.

Parameters:

variable Internal variable to set
value Current DLB variable value

Returns:

DLB_SUCCESS on success

DLB_ERR_NOENT if the variable does not exist

Get a DLB internal variable. See DLB_SetVariable().

int DLB_PrintVariables (int print_extended)

Print DLB internal variables.

Parameters:

print_extended If different to 0, print all options, including experimental, and its description

Returns:

DLB_SUCCESS on success

int DLB_PrintShmem (int num_columns, dlb_printshmem_flags_t print_flags)

Print the data stored in the shmem.

Parameters:

num_columns Number of columns to use when printing
print_flags Print options

Returns:

DLB_SUCCESS on success

const char* DLB_Strerror (int errnum)

Obtain a pointer to a string that describes the error code passed by argument.

Parameters:

errnum error code to consult

Returns:

pointer to string with the error description

int DLB_AutoSizerStart (void)

API call to adjust the resources of an application.

Returns:

DLB_SUCCESS on success

int DLB_AutoSizerEnd (void)

API call to adjust the resources of an application.

Returns:

DLB_SUCCESS on success

Author

Generated automatically by Doxygen for Dynamic Load Balance from the source code.