dlb.h¶
- Date:
Mon Jul 15 2024
NAME¶
dlb.h
SYNOPSIS¶
#include 'dlb_types.h'#include 'dlb_errors.h'#include <stdbool.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
DLB_ERR_NOCOMP if initialization options are incompatible
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_NOUPDT 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)¶
Perform a DLB Barrier among processes in the node.
Returns
DLB_SUCCESS on success
DLB_NOUPDT if the process has detached from the default barrier
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
This function performs a shared-memory-based barrier among all DLB processes in the node, unless thay have previously detached. The number of participants in the barrier is adaptive, which may produce undesired results if there is no synchronization between the attach/detach process and the barrier itself.
int DLB_BarrierAttach (void)¶
Attach process to the DLB Barrier team.
Returns
a positive integer with the updated number of participants
DLB_ERR_PERM if process was already attached, or if all processes detached
DLB_ERR_NOMEM if the process cannot attach to more barriers
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
DLB_ERR_NOSHMEM if cannot find shared memory
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)¶
Detach process from the DLB Barrier team.
Returns
a non-negative integer with the updated number of participants
DLB_ERR_PERM if process was already detached
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
DLB_ERR_NOSHMEM if cannot find shared memory
Remove process from the DLB Barrier team. Subsequent calls to DLB_Barrier from this process will have no effect. Other processes in the team will not synchronize with this process on their respective calls to DLB_Barrier.
dlb_barrier_t * DLB_BarrierNamedRegister (const char * barrier_name, dlb_barrier_flags_t flags)¶
Register, or obtain, a named barrier.
Parameters
barrier_name the name for the new barrier, or barrier to obtainflags barrier flags, see below
Returns
barrier associated to that name, or NULL on error
This function registers a new barrier or obtains the pointer to an already created barrier with the same name. The returned pointer is an opaque handle to use in other named barrier functions. This functions allows the following flags: DLB_BARRIER_LEWI_ON: the barrier may be used to perform LeWI operations DLB_BARRIER_LEWI_OFF: the barrier will not be used to perform LeWI operations DLB_BARRIER_LEWI_RUNTIME: whether this barrier will be used for LewI operations will be decided at run time
Names with commas (,) are supported, but will not work properly when using the –lewi-barrier-select option to select LeWI barriers at run time.
Note: DLB_BarrierNamedRegister and DLB_BarrierNamedGet are equivalent.
dlb_barrier_t * DLB_BarrierNamedGet (const char * barrier_name, dlb_barrier_flags_t flags)¶
Register, or obtain, a named barrier.
Parameters
barrier_name the name for the new barrier, or barrier to obtainflags barrier flags, see below
Returns
barrier associated to that name, or NULL on error
This function registers a new barrier or obtains the pointer to an already created barrier with the same name. The returned pointer is an opaque handle to use in other named barrier functions. This functions allows the following flags: DLB_BARRIER_LEWI_ON: the barrier may be used to perform LeWI operations DLB_BARRIER_LEWI_OFF: the barrier will not be used to perform LeWI operations DLB_BARRIER_LEWI_RUNTIME: whether this barrier will be used for LewI operations will be decided at run time
Names with commas (,) are supported, but will not work properly when using the –lewi-barrier-select option to select LeWI barriers at run time.
Note: DLB_BarrierNamedRegister and DLB_BarrierNamedGet are equivalent.
int DLB_BarrierNamed (dlb_barrier_t * barrier)¶
Perform a DLB Barrier using the named barrier among processes in the node.
Parameters
barrier named barrier
Returns
DLB_SUCCESS on success
DLB_NOUPDT if the process has detached from the barrier
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
This function is equivalent to DLB_Barrier, but providing a named barrier
int DLB_BarrierNamedAttach (dlb_barrier_t * barrier)¶
Attach process to the named barrier team.
Parameters
barrier named barrier to attach to
Returns
a positive integer with the updated number of participants
DLB_NOUPDT if process was already attached
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
DLB_ERR_NOSHMEM if cannot find shared memory
This function is equivalent to DLB_BarrierAttach, but providing a named barrier
int DLB_BarrierNamedDetach (dlb_barrier_t * barrier)¶
Detach process from the named barrier team.
Parameters
barrier named barrier to detach from
Returns
a non-negative integer with the updated number of participants
DLB_NOUPDT if process was already detached
DLB_ERR_NOCOMP if DLB Barrier is not enabled (option –barrier)
DLB_ERR_NOSHMEM if cannot find shared memory
DLB_ERR_PERM if all processes have detached from the barrier
This function is equivalent to DLB_BarrierDetach, but providing a named 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_SetObserverRole (bool thread_is_observer)¶
Modify the current thread DLB role to either observer or particpant.
Parameters
thread_is_observer true to set current thread to ‘observer’, false to ‘participant’
Returns
DLB_SUCCESS on success
By default, all threads are DLB participants, meaning that they invoke LeWI when needed or measure performance metrics when TALP is enabled. A thread that sets its role to ‘observer’ will still be able to invoke MPI calls or TALP functions, including managing monitoring regions, but it will not trigger LeWI nor any TALP measuring metrics.
