dlb_drom.h

Date:Fri Jul 15 2022

NAME

dlb_drom.h

SYNOPSIS


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

Functions

int DLB_DROM_Attach (void)
Attach current process to DLB system as DROM administrator.
int DLB_DROM_Detach (void)
Detach current process from DLB system.
int DLB_DROM_GetNumCpus (int *ncpus)
Get the number of CPUs in the node.
int DLB_DROM_GetPidList (int *pidlist, int *nelems, int max_len)
Get the list of running processes registered in the DLB system.
int DLB_DROM_GetProcessMask (int pid, dlb_cpu_set_t mask, dlb_drom_flags_t flags)
Get the process mask of the given PID.
int DLB_DROM_SetProcessMask (int pid, const_dlb_cpu_set_t mask, dlb_drom_flags_t flags)
Set the process mask of the given PID.
int DLB_DROM_PreInit (int pid, const_dlb_cpu_set_t mask, dlb_drom_flags_t flags, char ***next_environ)
Make room in the system for a new process with the given mask.
int DLB_DROM_PostFinalize (int pid, dlb_drom_flags_t flags)
Unregister a process from the DLB system.
int DLB_DROM_RecoverStolenCpus (int pid)
Recover previously stolen CPUs if they are idle.

Function Documentation

int DLB_DROM_Attach (void)

Attach current process to DLB system as DROM administrator.

Returns:

DLB_SUCCESS on success

Once the process is attached to DLB as DROM administrator, it may perform the below actions described in this file. This way, the process is able to query or modify other DLB running processes’ IDs and processes masks, as well as to make room in the system for creating another running process.

int DLB_DROM_Detach (void)

Detach current process from DLB system.

Returns:

DLB_SUCCESS on success

DLB_ERR_NOSHMEM if cannot find shared memory to dettach from

If previously attached, a process must call this function to correctly close file descriptors and clean data.

int DLB_DROM_GetNumCpus (int * ncpus)

Get the number of CPUs in the node.

Parameters:

ncpus the number of CPUs

Returns:

DLB_SUCCESS on success

int DLB_DROM_GetPidList (int * pidlist, int * nelems, int max_len)

Get the list of running processes registered in the DLB system.

Parameters:

pidlist The output list
nelems Number of elements in the list
max_len Max capacity of the list

Returns:

DLB_SUCCESS on success

DLB_ERR_NOSHMEM if cannot find shared memory

int DLB_DROM_GetProcessMask (int pid, dlb_cpu_set_t mask, dlb_drom_flags_t flags)

Get the process mask of the given PID.

Parameters:

pid Process ID to query its process mask, or 0 if current process
mask Current process mask of the target process
flags DROM options

Returns:

DLB_SUCCESS on success

DLB_NOTED if a new mask is given for the current process (replaces PollDROM)

DLB_ERR_NOPROC if target pid is not registered in the DLB system

DLB_ERR_TIMEOUT if the query is synchronous and times out

Accepted flags for this function:
DLB_SYNC_QUERY: Synchronous query. If the target process has any pending operations, the caller process gets blocked until the target process resolves them, or the query times out.

int DLB_DROM_SetProcessMask (int pid, const_dlb_cpu_set_t mask, dlb_drom_flags_t flags)

Set the process mask of the given PID.

Parameters:

pid Target Process ID to apply a new process mask, or 0 if current process
mask Process mask to set
flags DROM options

Returns:

DLB_SUCCESS on success

DLB_ERR_NOPROC if target pid is not registered in the DLB system

DLB_ERR_PDIRTY if target pid already has a pending operation

DLB_ERR_TIMEOUT if the query is synchronous and times out

DLB_ERR_PERM if the provided mask could not be stolen

Accepted flags for this function:
DLB_SYNC_QUERY: Synchronous query. If the target process has any pending operations, the caller process gets blocked until the target process resolves them, or the query times out.
DLB_SYNC_NOW: Force mask synchronization if target is the current process. If pid is 0 or current process id, and setting the new mask succeeds, this operation automatically forces the synchronization with the set_process_mask callback. It has the equivalent behaviour as invoking DLB_PollDROM_Update() after a successful operation.

int DLB_DROM_PreInit (int pid, const_dlb_cpu_set_t mask, dlb_drom_flags_t flags, char *** next_environ)

Make room in the system for a new process with the given mask.

Parameters:

pid Process ID that gets the reservation
mask Process mask to register
flags DROM options
next_environ environment to modify if the process is going to fork-exec

Returns:

DLB_SUCCESS on success

DLB_ERR_NOSHMEM if cannot find shared memory

DLB_ERR_INIT if the process is already registered

DLB_ERR_TIMEOUT if the query is synchronous and times out

DLB_ERR_PERM if the provided mask overlaps with an existing registered process and stealing option is not set

Accepted flags for this function:
DLB_STEAL_CPUS: Steal CPU ownership if necessary. If any CPU in mask is already registered in the system, steal the ownership from their original process.
DLB_RETURN_STOLEN: Return stolen CPUs when this process finalizes. If any CPU was stolen during the preinitialization, try to return those CPUs to their owners if they still exist.
DLB_SYNC_QUERY: Synchronous query. If the preinitialization needs to steal some CPU, the stealing operation is synchronous and thus will wait until the target process can release its CPU instead of causing oversubscription. This option may cause a time out if the target process does not update its mask in time.

This function can be called to preinitialize a future DLB running process, even if the current process ID does not match the future process, probably due to fork-exec mechanisms. Though in this case we need to modify the environment in order to not loose the preinitialization info.

Even if preinialized, a running process still needs to call DLB_Init() and DLB_Finalize() to take full advantage of all DLB features, but it is not mandatory.

int DLB_DROM_PostFinalize (int pid, dlb_drom_flags_t flags)

Unregister a process from the DLB system.

Parameters:

pid Process ID to unregister
flags DROM options

Returns:

DLB_SUCCESS on success

DLB_ERR_NOSHMEM if cannot find shared memory

DLB_ERR_NOPROC if target pid is not registered in the DLB system

Accepted flags for this function:
DLB_RETURN_STOLEN: Return stolen CPUs when this process finalizes. If any CPU was stolen during the preinitialization, try to return those CPUs to their owners if they still exist.

This function should be called after a preinitialized child process has finished its execution.

If the child process was DLB aware and called DLB_Init() and DLB_Finalize(), this function will return DLB_ERR_NOPROC, although that should not be considered as a wrong scenario.

int DLB_DROM_RecoverStolenCpus (int pid)

Recover previously stolen CPUs if they are idle.

Parameters:

pid Process ID

Returns:

DLB_SUCCESS on success

DLB_NOUPDT if the given process has not stolen CPUs

DLB_ERR_NOSHMEM if cannot find shared memory

DLB_ERR_NOPROC if target pid is not registered in the DLB system

If a running process abandoned the system without returning the previously stolen CPUs, this function may be called at any time to check if the target process is able to recover some of its original CPUs.

Author

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