dlb_sp.h

Date:Fri Jul 15 2022

NAME

dlb_sp.h

SYNOPSIS


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

Functions

dlb_handler_t DLB_Init_sp (int ncpus, const_dlb_cpu_set_t mask, const char *dlb_args)
Initialize DLB library and all its internal data structures.
int DLB_Finalize_sp (dlb_handler_t handler)
Finalize DLB library and clean up all its data structures for the specified handler. Must be called once by each created handler before exiting the system.
int DLB_Enable_sp (dlb_handler_t handler)
Enable DLB and all its features in case it was previously disabled, otherwise it has no effect.
int DLB_Disable_sp (dlb_handler_t handler)
Disable DLB actions for the specified handler.
int DLB_SetMaxParallelism_sp (dlb_handler_t handler, int max)
Set the maximum number of resources to be used by the handler.
int DLB_UnsetMaxParallelism_sp (dlb_handler_t handler)
Unset the maximum number of resources to be used by the handler.
int DLB_CallbackSet_sp (dlb_handler_t handler, dlb_callbacks_t which, dlb_callback_t callback, void *arg)
Setter for DLB callbacks.
int DLB_CallbackGet_sp (dlb_handler_t handler, dlb_callbacks_t which, dlb_callback_t *callback, void **arg)
Getter for DLB callbacks.
int DLB_Lend_sp (dlb_handler_t handler)
Lend all the current CPUs.
int DLB_LendCpu_sp (dlb_handler_t handler, int cpuid)
Lend a specific CPU.
int DLB_LendCpus_sp (dlb_handler_t handler, int ncpus)
Lend a specific amount of CPUs, only useful for systems that do not work with cpu masks.
int DLB_LendCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)
Lend a set of CPUs.
int DLB_Reclaim_sp (dlb_handler_t handler)
Reclaim all the CPUs that are owned by the subprocess.
int DLB_ReclaimCpu_sp (dlb_handler_t handler, int cpuid)
Reclaim a specific CPU that are owned by the subprocess.
int DLB_ReclaimCpus_sp (dlb_handler_t handler, int ncpus)
Reclaim a specific amount of CPUs that are owned by the subprocess.
int DLB_ReclaimCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)
Reclaim a set of CPUs.
int DLB_AcquireCpu_sp (dlb_handler_t handler, int cpuid)
Acquire a specific CPU.
int DLB_AcquireCpus_sp (dlb_handler_t handler, int ncpus)
Acquire a specific amount of CPUs.
int DLB_AcquireCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)
Acquire a set of CPUs.
int DLB_AcquireCpusInMask_sp (dlb_handler_t handler, int ncpus, const_dlb_cpu_set_t mask)
Acquire some CPUs from a subset of CPUs.
int DLB_Borrow_sp (dlb_handler_t handler)
Borrow all the possible CPUs registered on DLB.
int DLB_BorrowCpu_sp (dlb_handler_t handler, int cpuid)
Borrow a specific CPU.
int DLB_BorrowCpus_sp (dlb_handler_t handler, int ncpus)
Borrow a specific amount of CPUs.
int DLB_BorrowCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)
Borrow a set of CPUs.
int DLB_BorrowCpusInMask_sp (dlb_handler_t handler, int ncpus, const_dlb_cpu_set_t mask)
Borrow some CPUs from a subset of CPUs.
int DLB_Return_sp (dlb_handler_t handler)
Return claimed CPUs of other subprocesses.
int DLB_ReturnCpu_sp (dlb_handler_t handler, int cpuid)
Return the specific CPU if it has been reclaimed.
int DLB_ReturnCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)
Return a set of CPUs if some of them have been reclaimed.
int DLB_PollDROM_sp (dlb_handler_t handler, int *ncpus, dlb_cpu_set_t mask)
Poll DROM module to check if the subprocess needs to adapt to a new mask or number of CPUs.
int DLB_PollDROM_Update_sp (dlb_handler_t handler)
Poll DROM module to check if the subprocess needs to adapt to a new mask and update it if necessary using the registered callbacks.
int DLB_CheckCpuAvailability_sp (dlb_handler_t handler, int cpuid)
Check whether the specified CPU is being used by another subprocess.
int DLB_SetVariable_sp (dlb_handler_t handler, const char *variable, const char *value)
Change the value of a DLB internal variable.
int DLB_GetVariable_sp (dlb_handler_t handler, const char *variable, char *value)
Query the value of a DLB internal variable.
int DLB_PrintVariables_sp (dlb_handler_t handler, int print_extended)
Print DLB internal variables.

Function Documentation

dlb_handler_t DLB_Init_sp (int ncpus, const_dlb_cpu_set_t mask, const char * dlb_args)

Initialize DLB library and all its internal data structures.

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_handler to use on subsequent DLB calls

Parameters ncpus and mask are used to register CPUs owned by the calling subprocess 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_sp (dlb_handler_t handler)

Finalize DLB library and clean up all its data structures for the specified handler. Must be called once by each created handler before exiting the system.

Parameters:

handler subprocess identifier

Returns:

DLB_SUCCESS on success

int DLB_Enable_sp (dlb_handler_t handler)

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

Parameters:

handler subprocess identifier

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if DLB is already enabled

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_sp (dlb_handler_t handler)

Disable DLB actions for the specified handler.

Parameters:

handler subprocess identifier

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if DLB is already disabled

This call resets the original resources for the subprocess 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 subprocess.

int DLB_SetMaxParallelism_sp (dlb_handler_t handler, int max)

Set the maximum number of resources to be used by the handler.

Parameters:

handler subprocess identifier
max max number of CPUs

Returns:

DLB_SUCCESS on success

Used to delimit sections of the code that the developer knows that only a maximum number of CPUs can benefit the execution. If a subprocess 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_sp (dlb_handler_t handler)

Unset the maximum number of resources to be used by the handler.

Parameters:

handler subprocess identifier

Returns:

DLB_SUCCESS on success

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

int DLB_CallbackSet_sp (dlb_handler_t handler, dlb_callbacks_t which, dlb_callback_t callback, void * arg)

Setter for DLB callbacks.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, dlb_callbacks_t which, dlb_callback_t * callback, void ** arg)

Getter for DLB callbacks.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler)

Lend all the current CPUs.

Parameters:

handler subprocess identifier

Returns:

DLB_SUCCESS on success

DLB_ERR_DISBLD if DLB is disabled

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

int DLB_LendCpu_sp (dlb_handler_t handler, int cpuid)

Lend a specific CPU.

Parameters:

handler subprocess identifier
cpuid CPU id to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_DISBLD if DLB is disabled

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

int DLB_LendCpus_sp (dlb_handler_t handler, int ncpus)

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

Parameters:

handler subprocess identifier
ncpus number of CPUs to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_DISBLD if DLB is disabled

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

int DLB_LendCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)

Lend a set of CPUs.

Parameters:

handler subprocess identifier
mask CPU mask to lend

Returns:

DLB_SUCCESS on success

DLB_ERR_DISBLD if DLB is disabled

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

int DLB_Reclaim_sp (dlb_handler_t handler)

Reclaim all the CPUs that are owned by the subprocess.

Parameters:

handler subprocess identifier

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_DISBLD if DLB is disabled

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

int DLB_ReclaimCpu_sp (dlb_handler_t handler, int cpuid)

Reclaim a specific CPU that are owned by the subprocess.

Parameters:

handler subprocess identifier
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_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 subprocess.

int DLB_ReclaimCpus_sp (dlb_handler_t handler, int ncpus)

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

Parameters:

handler subprocess identifier
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_DISBLD if DLB is disabled

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

int DLB_ReclaimCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)

Reclaim a set of CPUs.

Parameters:

handler subprocess identifier
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_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 subprocess.

int DLB_AcquireCpu_sp (dlb_handler_t handler, int cpuid)

Acquire a specific CPU.

Parameters:

handler subprocess identifier
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_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 subprocess the call is equivalent to a reclaim action. Otherwise the subprocess attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpus_sp (dlb_handler_t handler, int ncpus)

Acquire a specific amount of CPUs.

Parameters:

handler subprocess identifier
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_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 subprocess the call is equivalent to a reclaim action. Otherwise the subprocess attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpuMask_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)

Acquire a set of CPUs.

Parameters:

handler subprocess identifier
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_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 subprocess the call is equivalent to a reclaim action. Otherwise the subprocess attempts to acquire a specific CPU in case it is available or enqueue a request if it’s not.

int DLB_AcquireCpusInMask_sp (dlb_handler_t handler, int ncpus, const_dlb_cpu_set_t mask)

Acquire some CPUs from a subset of CPUs.

Parameters:

handler subprocess identifier
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_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_sp (dlb_handler_t handler)

Borrow all the possible CPUs registered on DLB.

Parameters:

handler subprocess identifier

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_sp (dlb_handler_t handler, int cpuid)

Borrow a specific CPU.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, int ncpus)

Borrow a specific amount of CPUs.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)

Borrow a set of CPUs.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, int ncpus, const_dlb_cpu_set_t mask)

Borrow some CPUs from a subset of CPUs.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler)

Return claimed CPUs of other subprocesses.

Parameters:

handler subprocess identifier

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 subprocess but stating that the current subprocess 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_sp (dlb_handler_t handler, int cpuid)

Return the specific CPU if it has been reclaimed.

Parameters:

handler subprocess identifier
cpuid CPU 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 subprocess but stating that the current subprocess 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_sp (dlb_handler_t handler, const_dlb_cpu_set_t mask)

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

Parameters:

handler subprocess identifier
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 subprocess but stating that the current subprocess 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_sp (dlb_handler_t handler, int * ncpus, dlb_cpu_set_t mask)

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

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler)

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

Parameters:

handler subprocess identifier

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_sp (dlb_handler_t handler, int cpuid)

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

Parameters:

handler subprocess identifier
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_SetVariable_sp (dlb_handler_t handler, const char * variable, const char * value)

Change the value of a DLB internal variable.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, const char * variable, char * value)

Query the value of a DLB internal variable.

Parameters:

handler subprocess identifier
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_sp (dlb_handler_t handler, int print_extended)

Print DLB internal variables.

Parameters:

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

Returns:

DLB_SUCCESS on success

Author

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