A group of user processes that together execute ALP programs. More...

Public Member Functions
	Launcher (const size_t process_id=0, const size_t nprocs=1, const std::string hostname="localhost", const std::string port="0")
	Constructs a new grb::Launcher. More...

template<typename T , typename U >
RC	exec (AlpTypedFunc< T, U > alp_program, const T &data_in, U &data_out, const bool broadcast=false) const
	Executes a given ALP program using the user processes encapsulated by this launcher group. More...

template<typename U >
RC	exec (AlpUntypedFunc< U > alp_program, const void *data_in, const size_t in_size, U &data_out, const bool broadcast=false) const
	Executes a given ALP program using the user processes encapsulated by this launcher group. More...

Static Public Member Functions
static RC	finalize ()
	Releases all ALP resources. More...

Detailed Description

template<enum EXEC_MODE mode, enum Backend backend>
class grb::Launcher< mode, backend >

A group of user processes that together execute ALP programs.

Allows an application to run any ALP program. Input data may be passed through a user-defined type. Output data will be retrieved via another user- defined type.

For backends that support multiple user processes, the caller may explicitly set the process ID and total number of user processes. If the launcher is requested to spawn new user processes, i.e., if it is constructed using the AUTOMATIC mode, then the backend spawns an implementation-defined number of additional user processes beyond that corresponding to the process constructing the launcher instance, that then jointly execute ALP programs in parallel.

The intended use is to ‘just call’ the exec function, which must be accepted by any backend in any implementation, to execute any ALP program.

Template Parameters

mode	Which EXEC_MODE the Launcher should adhere to.
backend	Which backend to use. This is a hidden template argument that defaults to the backend selected at compile time through `grbcxx` or `alpcxx`.

Constructor & Destructor Documentation

◆ Launcher()

Launcher	(	const size_t	process_id = `0`,
		const size_t	nprocs = `1`,
		const std::string	hostname = `"localhost"`,
		const std::string	port = `"0"`
	)

inline

Constructs a new grb::Launcher.

In AUTOMATIC mode, a single root user processes issues a call to this constructor. In all other modes, a call to this constructor is collective: all nprocs processes that are to form a single launcher group, must make a simultaneous call to this constructor and must do so with consistent arguments.

Note: One may note that in all modes, a call to this constructor must be collective; it is just that in automatic mode there is but one process involved with the collective call (i.e., nprocs is one).

There is an implementation-defined time-out for the creation of a launcher group. The default arguments to the below are consistent with the automatic launcher mode.

Parameters

[in]	process_id	The user process ID of the calling process. The value must be larger or equal to 0. This value must be strictly smaller than nprocs. This value must be unique to the calling process within this collective call across all nprocs user processes. This number must be strictly smaller than nprocs. Optional: the default is 0.
[in]	nprocs	The total number of user processes making a collective call to this function. Optional: the default is 1.
[in]	hostname	The hostname of one of the user processes. Optional: the default is ‘localhost’.
[in]	port	A free port number at hostname. This port will be used for TCP connections to hostname if and only if nprocs is larger than one. Optional: the default value is ‘0’.

While these arguments are generic and would work with most network fabrics, some modes such as indeed FROM_MPI may require other arguments for constructing a launcher. In terms of specification, only AUTOMATIC and MANUAL are required to implement this specific constructor signature, including the specified defaults for each argument. All aforementioned default values must be legal for the AUTOMATIC and MANUAL modes.

Any other mode in grb::EXEC_MODE, with possibly different constructor signatures from those listed here, are both optional and implementation- specific.

Note: An implementation or backend may define further constraints on the input arguments, such as, obviously, on hostname and port, but also on nprocs and, as a result, on process_id.; The most obvious such restriction has backends supporting only one user process not accepting nprocs larger than 1.

Exceptions

invalid_argument	If nprocs is zero.
invalid_argument	If process_id is greater than or equal to nprocs.
std::invalid_argument	If nprocs is zero.
std::invalid_argument	If process_id is larger than or equal to nprocs.

Member Function Documentation

◆ exec() [1/2]

RC exec	(	AlpTypedFunc< T, U >	alp_program,
		const T &	data_in,
		U &	data_out,
		const bool	broadcast = `false`
	)		const

inline

Executes a given ALP program using the user processes encapsulated by this launcher group.

Calling this function, depending on whether the automatic, manual, or from MPI mode was selected, will either:

use processes spawned by the ALP implemenation and use those, as well as the process which had constructed this launcher instance, to jointly execute the given alp_program, or
employ the given processes that are managed by the user application and used to construct this launcher instance to execute the given alp_program.

This is a collective function call– all processes in the launcher group must make a simultaneous call to this function and must do so using consistent arguments.

Template Parameters

T	The type of the data to pass to the ALP program as input. This must be a POD type that contains no pointers.

Note: In fact, T may be standard layout and contain no pointers, or it may be trivially copiable and contain no pointers.

For calls with broadcast false, T must furthermore be default-constructible (and have meaningful default values that allow for successful multi-process execution).

For programs or entry points that are solely to be called from manual or from MPI modes with broadcast false, there are no constraints on the type T since instances of T are only ever passed within the pre-existing user process, and never communicated across user processes.

Template Parameters

U	The type of the output data to pass back to the caller. This may be of any type.

When mode is AUTOMATIC, the type U must be default-constructible.

Parameters

[in]	alp_program	The user program to be executed.
[in]	data_in	Input data of user-defined type T.
[out]	data_out	Output data of user-defined type U.
[in]	broadcast	Whether the input should be broadcast from user process 0 to all other user processes. Optional; the default value is `false`.

When in automatic mode and broadcast is false, the input data data_in will only be available at user process with ID 0– any other user processes will receive a default-constructed data_in instead. When in automatic mode and broadcast is true, the input data data_in will be available at all user processes instead.

When in MANUAL or FROM_MPI mode, each user process should collectively call this function. If broadcast is false, the input data will be passed from the external calling process to the corresponding ALP user processes in a one-to-one manner. Should broadcast be true, then the initial input data passed this way is overwritten for user processes \( s > 0 \) with the data_in passed at user process zero.

Only in MANUAL or FROM_MPI modes will the output of any user processes with ID \( s > 0 \) be returned to all the processes that collectively call this function.

In AUTOMATIC mode, the output at \( s > 0 \) is lost. Only the output of the first user process \( s = 0 \) will be passed back to the root process that called this function.

Note: The default for broadcast is false as it is the variant that implies the least cost when launching a program.; The FROM_MPI mode is specific to this imlementation and need not be provided as part of the specification.

Returns: grb::SUCCESS If the execution proceeded as intended.; grb::ILLEGAL If broadcast was false and mode was AUTOMATIC, but T not default-constructible.; grb::PANIC If an unrecoverable error was encountered while attempting to execute, attempting to terminate, or while executing, the given program.

Warning: Even if grb::SUCCESS is returned, an algorithm may fail to achieve its intended result– for example, an iterative solver may fail to converge. A good programming pattern has that U either a) is an error code for the algorithm used (e.g., int or grb::RC), or that b) U is a struct that contains such an error code.

◆ exec() [2/2]

RC exec	(	AlpUntypedFunc< U >	alp_program,
		const void *	data_in,
		const size_t	in_size,
		U &	data_out,
		const bool	broadcast = `false`
	)		const

inline

Executes a given ALP program using the user processes encapsulated by this launcher group.

This variant of exec has that data_in is of a variable byte size, instead of a fixed (POD pointer-less) type. We refer to the given function as an untyped ALP function (since the input is a raw pointer), whereas the other variant executes typed ALP functions instead.

If broadcast is true, all bytes are broadcast from the user process with ID zero to all other user processes.

Note: When in MANUAL or FROM_MPI mode, this implies any arguments passed in a process-to-process manner will be lost.

If broadcast is false and the launcher in AUTOMATIC mode, then the user processes with ID \( s > 0 \) will receive data_in equal to nullptr and in_size equal to zero.

See the typed ALP exec variant for more detailed comments, which also transfer to this untyped variant.

Parameters

[in]	alp_program	The (untyped) user program to be executed.
[in]	data_in	Pointer to raw input byte data.
[in]	in_size	The number of bytes the input data consists of.
[out]	data_out	Output data of user-defined type U. The output data should be available at user process with ID zero.
[in]	broadcast	Whether the input should be broadcast from user process 0 to all other user processes. Optional; the default value is false.

Returns: grb::SUCCESS If the execution proceeded as intended.; grb::ILLEGAL If in_size is larger than zero but data_in is equal to nullptr.; grb::PANIC If an unrecoverable error was encountered while attempting to execute, attempting to terminate, or while executing, the given program.

◆ finalize()

static RC finalize ( )

inlinestatic

Releases all ALP resources.

After a call to this function, no further ALP programs may launched using any grb::Launcher or grb::Benchmarker instance. Implementations and backends shall under no circumstance require a call to this function; any use of this function shall remain purely optional.

Warning: After a call to this function, also any subsequent call to the deprecated grb::init and grb::finalize will no longer be accepted.

After a call to this function, the only way to once again run ALP programs is to use the grb::Launcher from a different process.

Warning: Therefore, use this function with care and preferably only just before exiting the process– or not at all.

Returns: grb::SUCCESS The resources have successfully and permanently been released.; grb::PANIC An unrecoverable error has been encountered and the user program is encouraged to exit as quickly as possible. The state of the ALP library has become undefined and should no longer be used.

Note: In the terminology of the Message Passing Interface (MPI), this function is similar to MPI_Finalize().

Warning: Different from MPI, however, a call to this function at program exit is not mandatory.; An application that launches ALP programs in grb::FROM_MPI mode that calls this function, must (afterwards) still make a call to MPI_Finalize().

The documentation for this class was generated from the following file:

exec.hpp

Public Member Functions

Static Public Member Functions

Detailed Description

template<enum EXEC_MODE mode, enum Backend backend> class grb::Launcher< mode, backend >

Constructor & Destructor Documentation

◆ Launcher()

Member Function Documentation

◆ exec() [1/2]

◆ exec() [2/2]

◆ finalize()

template<enum EXEC_MODE mode, enum Backend backend>
class grb::Launcher< mode, backend >