#include "apis/dlb_drom.h"
#include "LB_comm/shmem_cpuinfo.h"
#include "LB_comm/shmem_procinfo.h"
#include "LB_core/spd.h"
#include "LB_core/DLB_kernel.h"
#include "apis/dlb_errors.h"
#include "support/debug.h"
#include "support/dlb_common.h"
#include "support/env.h"
#include "support/mask_utils.h"
#include "support/options.h"
#include <sched.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

Include dependency graph for DLB_interface_drom.c:

Functions
DLB_EXPORT_SYMBOL int	DLB_DROM_Attach (void)
	Attach current process to DLB system as DROM administrator. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_Detach (void)
	Detach current process from DLB system. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_GetNumCpus (int *ncpus)
	Get the number of CPUs in the node. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_GetPidList (int pidlist, int nelems, int max_len)
	Get the list of running processes registered in the DLB system. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_GetProcessMask (int pid, dlb_cpu_set_t mask, dlb_drom_flags_t flags)
	Get the process mask of the given PID. More...

DLB_EXPORT_SYMBOL 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. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_SetProcessMaskStr (int pid, const char *mask, dlb_drom_flags_t flags)
	Set the process mask of the given PID. More...

DLB_EXPORT_SYMBOL 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. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_PostFinalize (int pid, dlb_drom_flags_t flags)
	Unregister a process from the DLB system. More...

DLB_EXPORT_SYMBOL int	DLB_DROM_RecoverStolenCpus (int pid)
	Recover previously stolen CPUs if they are idle. More...

Function Documentation

◆ DLB_DROM_Attach()

DLB_EXPORT_SYMBOL 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.

◆ DLB_DROM_Detach()

DLB_EXPORT_SYMBOL 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.

◆ DLB_DROM_GetNumCpus()

DLB_EXPORT_SYMBOL int DLB_DROM_GetNumCpus ( int * ncpus )

Get the number of CPUs in the node.

Parameters

[out] ncpus the number of CPUs

Returns: DLB_SUCCESS on success

◆ DLB_DROM_GetPidList()

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

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

Parameters

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

Returns: DLB_SUCCESS on success; DLB_ERR_NOSHMEM if cannot find shared memory

◆ DLB_DROM_GetProcessMask()

DLB_EXPORT_SYMBOL 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

[in]	pid	Process ID to query its process mask, or 0 if current process
[out]	mask	Current process mask of the target process
[in]	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_DROM_FLAGS_NONE: No special behavior.

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_DROM_SetProcessMask()

DLB_EXPORT_SYMBOL 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

[in]	pid	Target Process ID to apply a new process mask, or 0 if current process
[in]	mask	Process mask to set
[in]	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_DROM_FLAGS_NONE: Default behavior.
    - If the target is a different process: no special behavior.
    - If the target is the current process and the mask can be applied immediately:
        forces synchronization using the set_process_mask callback.
        This is functionally equivalent to calling DLB_PollDROM_Update() after a
        successful operation.

DLB_SYNC_QUERY: Perform a synchronous query.
    - If the target process has any pending operations, the caller is blocked until
    those operations are resolved or the query times out.

DLB_SYNC_NOW: -- DEPRECATED --

DLB_NO_SYNC: Avoid mask synchronization even if target is current process.

◆ DLB_DROM_SetProcessMaskStr()

DLB_EXPORT_SYMBOL int DLB_DROM_SetProcessMaskStr	(	int	pid,
		const char *	mask,
		dlb_drom_flags_t	flags
	)

Set the process mask of the given PID.

Parameters

[in]	pid	Target Process ID to apply a new process mask, or 0 if current process
[in]	mask	Process mask to set
[in]	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

This function is equivalent to DLB_DROM_SetProcessMask, only that it accepts the input mask as a const char pointer type.

◆ DLB_DROM_PreInit()

DLB_EXPORT_SYMBOL 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

[in]	pid	Process ID that gets the reservation
[in]	mask	Process mask to register
[in]	flags	DROM options
[in,out]	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_DROM_FLAGS_NONE: No special behavior.

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.

◆ DLB_DROM_PostFinalize()

DLB_EXPORT_SYMBOL int DLB_DROM_PostFinalize	(	int	pid,
		dlb_drom_flags_t	flags
	)

Unregister a process from the DLB system.

Parameters

[in]	pid	Process ID to unregister
[in]	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_DROM_FLAGS_NONE: No special behavior.

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.

◆ DLB_DROM_RecoverStolenCpus()

DLB_EXPORT_SYMBOL int DLB_DROM_RecoverStolenCpus ( int pid )

Recover previously stolen CPUs if they are idle.

Parameters

[in] 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.

Functions

Function Documentation

◆ DLB_DROM_Attach()

◆ DLB_DROM_Detach()

◆ DLB_DROM_GetNumCpus()

◆ DLB_DROM_GetPidList()

◆ DLB_DROM_GetProcessMask()

◆ DLB_DROM_SetProcessMask()

◆ DLB_DROM_SetProcessMaskStr()

◆ DLB_DROM_PreInit()

◆ DLB_DROM_PostFinalize()

◆ DLB_DROM_RecoverStolenCpus()