dlb_sp.h¶
- Date:
Mon Jul 15 2024
NAME¶
dlb_sp.h
SYNOPSIS¶
#include 'dlb_types.h'#include 'dlb_errors.h'Functions¶
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 0mask optional, initial CPU mask to register, or NULLdlb_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 identifiermax 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 identifierwhich 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_sp (dlb_handler_t handler, dlb_callbacks_t which, dlb_callback_t * callback, void ** arg)¶
Getter for DLB callbacks.
Parameters
handler subprocess identifierwhich 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_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 identifiercpuid 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 identifierncpus 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 identifiermask 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 identifiercpuid 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 identifierncpus 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 identifiermask 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 identifiercpuid 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 identifierncpus 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 identifiermask 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 identifierncpus 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_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 identifiercpuid 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 identifierncpus 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 identifiermask 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 identifierncpus 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_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 identifiercpuid 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 identifiermask 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 identifierncpus 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_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 identifiercpuid 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 identifiervariable 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_sp (dlb_handler_t handler, const char * variable, char * value)¶
Query the value of a DLB internal variable.
Parameters
handler subprocess identifiervariable 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_sp (dlb_handler_t handler, int print_extended)¶
Print DLB internal variables.
Parameters
handler subprocess identifierprint_extended If different to 0, print all options, including experimental, and its description
Returns
DLB_SUCCESS on success
