dlb.h¶
| Date: | Fri Jul 15 2022 |
|---|
NAME¶
dlb.h
SYNOPSIS¶
#include 'dlb_types.h'#include 'dlb_errors.h'Functions¶
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 0mask optional, initial CPU mask to register, or NULLdlb_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 registernext_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 typecallback function pointer to registerarg 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 typecallback registered callback function for the specified callback typearg 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 acquiremask 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 borrowmask 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 CPUsmask 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 setvalue 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 setvalue 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 printingprint_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.
