dlb_drom.h¶

Date:: Mon Jul 15 2024

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: – DEPRECATED, ENABLED BY DEFAULT unless DLB_NO_SYNC is
used – If the target pid is 0, or self pid, and the new mask can be
immediate applied, force mask synchronization. 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.
DLB_NO_SYNC: Only if the target is the current process, disable
automatic mask synchronization

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.