Launcher< mode, backend > Class Template Reference

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

#include <exec.hpp>

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 (void(*alp_program)(const T &, U &), 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 (void(*alp_program)(const void *, const size_t, U &), 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 the same type.

For backends that support multiple user processes, the caller may explicitly set the process ID and total number of user processes.

The intended use is to ‘just call’ the exec function, which should be accepted by any backend.

Template Parameters

mode	Which EXEC_MODE the Launcher should adhere to.
backend	Which backend is to be used.

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.

This constructor is a collective call; all nprocs processes that form a single launcher group must make a simultaneous call to this constructor.

There is an implementation-defined time-out for the creation of a launcher group.

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

Exceptions

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

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 is that backends supporting only one user process must not accept nprocs larger than 1.

All aforementioned default values shall always be legal.

Member Function Documentation

exec() [1/2]

RC exec ( void(*)(const 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 or manual/MPI mode was selected, will either spawn the maximum number of available user processes and then execute the given program, or it will 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.
U	The type of the output data to pass back to the caller.

Parameters

[in]	alp_program	The user program to be executed.
[in]	data_in	Input data of user-defined type T.

When in automatic mode and broadcast is false, the data will only be available at user process with ID 0. When in automatic mode and broadcast is true, the data will be available at all user processes. When in manual mode, the data will be available to this user process only, with "this process" corresponding to the process that calls this function.

Parameters

[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::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., grb::RC), or b) that U contains such an error code.

exec() [2/2]

RC exec ( void(*)(const void *, const size_t, 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 type. If broadcast is true and the launcher is instantiated using the grb::AUTOMATIC mode, all bytes are broadcast to all user processes.

Parameters

[in]	alp_program	The 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::PANIC If an unrecoverable error was encountered while attempting to execute, attempting to terminate, or while executing, the given program.

For more details, see the other version of this function.

finalize()

static RC finalize ( )

inlinestatic

Releases all ALP resources.

After a call to this function, no further ALP programs may launched using the grb::Launcher and grb::Benchmarker. Also the use of grb::init and grb::finalize will no longer be accepted.

Warning

grb::init and grb::finalize are deprecated.

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

Warning

Therefore, use this function with care and preferably only just before exiting the process.

A well-behaving program calls this function, or grb::Benchmarker::finalize, exactly once before its process terminates, or just after the guaranteed last invocation of an ALP program.

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 the ALP equivalent of the MPI_Finalize().

In grb::AUTOMATIC mode when using a parallel backend that uses MPI to auto-parallelise the ALP computations, MPI is never explicitly exposed to the user application. This use case necessitates the specification of this function.

Thus, and in particular, an ALP program launched in grb::AUTOMATIC mode while using the grb::BSP1D or the grb::hybrid backends with ALP compiled using LPF that in turn is configured to use an MPI-based engine, should make sure to call this function before program exit.

An application that launches ALP programs in grb::FROM_MPI mode must still call this function, even though a proper such application makes its own call to MPI_Finalize(). This does not induce improper behaviour since calling this function using a launcher instance in grb::FROM_MPI mode translates, from an MPI perspective, to a no-op.

---

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

• exec.hpp