#include <genesis/utils/core/options.hpp>

Detailed Description

Simple Options class for application-wide configuration and settings.

Definition at line 57 of file options.hpp.

Public Member Functions
bool	allow_file_overwriting () const
	Get whether Genesis is allowed to overwrite files when outputting data. More...

void	allow_file_overwriting (bool value)
	Set whether Genesis is allowed to overwrite files when outputting data. More...

std::vector< std::string > const &	command_line () const
	Returns an array of strings containing the program's command line arguments. More...

void	command_line (int const argc, char const const argv)
	Set arguments to the program's command line options. More...

std::string	command_line_string () const
	Returns a string containing the program's command line arguments. More...

std::shared_ptr< ThreadPool >	global_thread_pool () const
	Return a global thread pool to be used for parallel computations. More...

size_t	global_thread_pool_size () const
	Get the number of threads allocatd in the pool, plus one for the main thread. More...

void	init_global_thread_pool ()
	Initialize the global thread pool to be used for parallel computations. More...

void	init_global_thread_pool (size_t num_threads, size_t max_queue_size=0)
	Initialize the global thread pool to be used for parallel computations. More...

InputReadingThreadPolicy	input_reading_thread_policy ()
	Get the policy for the threading of input source reading. More...

void	input_reading_thread_policy (InputReadingThreadPolicy policy)
	Set the policy for the threading of input source reading. More...

std::default_random_engine &	random_engine ()
	Return a thread-local engine for random number generation. More...

unsigned long	random_seed () const
	Returns the random seed that was used to initialize the engine. More...

void	random_seed (unsigned long const seed)
	Set a specific global seed for the random engine initialization. More...

size_t	seed_counter () const
	Return the number of seeds used to initialize thread-local random engines. More...

Static Public Member Functions
static Options &	get ()
	Returns a single instance of this class. More...

Public Types
enum	InputReadingThreadPolicy { kStrict, kTrivialAsync, kAllAsync }
	Decide how to use threads for input reading. More...

Member Function Documentation

◆ allow_file_overwriting() [1/2]

bool allow_file_overwriting ( ) const

inline

Get whether Genesis is allowed to overwrite files when outputting data.

See allow_file_overwriting( bool ) for details.

Definition at line 359 of file options.hpp.

◆ allow_file_overwriting() [2/2]

void allow_file_overwriting ( bool value )

inline

Set whether Genesis is allowed to overwrite files when outputting data.

The option is false by default, which causes Genesis to throw an execption when it attempts to write to a file that is already existing, as long as only the internal file writing functions are used, such as the to_file() function to get a target for the writer classes. We of course cannot control any independent file operations.

By setting this option to true, files are silently overwritten in case they already exist. This has to be activated explicitly in order to avoid losing files by accident.

See also: file_output_stream()

Definition at line 377 of file options.hpp.

◆ command_line() [1/2]

std::vector<std::string> const& command_line ( ) const

inline

Returns an array of strings containing the program's command line arguments.

Definition at line 82 of file options.hpp.

◆ command_line() [2/2]

void command_line	(	int const	argc,
		char const const	argv
	)

inline

Set arguments to the program's command line options.

If the program is run from the command line, this method has to be used to properly propagate the command line options to this options class.

Definition at line 106 of file options.hpp.

◆ command_line_string()

std::string command_line_string ( ) const

inline

Returns a string containing the program's command line arguments.

Definition at line 90 of file options.hpp.

◆ get()

static Options& get ( )

inlinestatic

Returns a single instance of this class.

Definition at line 68 of file options.hpp.

◆ global_thread_pool()

std::shared_ptr<ThreadPool> global_thread_pool ( ) const

inline

Return a global thread pool to be used for parallel computations.

The thread pool has to be initialized with init_global_thread_pool() first.

Note: In cases where we need to limit our number of spawned threads to some maximum amount, we might even want to use this pool for our readers, which often use AsynchronousReader, thus spawning threads to minimize i/o wait times; but this is not recommended, as the threads waiting for i/o might then be unnecessaryliy wait in the thread pool, just for them to then relatively quickly (compared to potential wait times in the thread queue) execute their disk operation. However, for more complex reading such as from compressed files, we might want to use the global thread pool after all. See BaseInputSource::is_trivial()

Definition at line 268 of file options.hpp.

◆ global_thread_pool_size()

size_t global_thread_pool_size ( ) const

inline

Get the number of threads allocatd in the pool, plus one for the main thread.

This is because with our ProactiveFuture implementaiton, the main thread does work as well.

Definition at line 284 of file options.hpp.

◆ init_global_thread_pool() [1/2]

void init_global_thread_pool ( )

inline

Initialize the global thread pool to be used for parallel computations.

This overload uses the result of guess_number_of_threads() to get the overall number of threads to use, and initializes the pool to use one fewer than that, to account for the main thread also doing work. As our ThreadPool implementation uses what we call a ProactiveFuture, the main thread will start processing tasks from the pool queue while it is waiting for results to get ready.

After calling this function, global_thread_pool() can be used to obtain the global thread pool to enqueue work.

Definition at line 215 of file options.hpp.

◆ init_global_thread_pool() [2/2]

void init_global_thread_pool	(	size_t	num_threads,
		size_t	max_queue_size = `0`
	)

inline

Initialize the global thread pool to be used for parallel computations.

This initializes the pool to have exactly as many threads as provided by num_threads here. Note that the main thread will also do work, so it is recommended to keep the num_threads at at least one fewer than the hardware concurrency (or other upper limit of threads, such as OpenMP or Slum limits, that you might want to keep). Use the overload init_global_thread_pool() without any arguments to do this automatically.

If num_threads is 0, the thread pool is initialized with no threads at all, meaning that all enqueued work will instead be processed by the main thread once it wants to obtain the results of tasks. This essentially renders the thread pool into a lazy evaluating task queue.

After calling this function, global_thread_pool() can be used to obtain the global thread pool to enqueue work.

Definition at line 244 of file options.hpp.

◆ input_reading_thread_policy() [1/2]

InputReadingThreadPolicy input_reading_thread_policy ( )

inline

Get the policy for the threading of input source reading.

Definition at line 345 of file options.hpp.

◆ input_reading_thread_policy() [2/2]

void input_reading_thread_policy ( InputReadingThreadPolicy policy )

inline

Set the policy for the threading of input source reading.

Definition at line 337 of file options.hpp.

◆ random_engine()

std::default_random_engine& random_engine ( )

inline

Return a thread-local engine for random number generation.

Caveat: The engines are thread-local, and hence thread-safe. However, generally, in a multi-threaded setting, the order of execution in not deterministic, and hence results might not be reproducible, even when using a fixed seed.

Definition at line 168 of file options.hpp.

◆ random_seed() [1/2]

unsigned long random_seed ( ) const

inline

Returns the random seed that was used to initialize the engine.

This is the global seed that is used as a basis for all thread-local seeding.

Definition at line 124 of file options.hpp.

◆ random_seed() [2/2]

void random_seed ( unsigned long const seed )

inline

Set a specific global seed for the random engine initialization.

This (re)sets the global seed for the thread-local random engines. The engine of the thread where this function is called from, as well as any thread spawned after, is reseeded using this seed plus a counter based on the number of spawned threads.

On startup, the seed is initialized using the current system time, and that exact seed is used for the main thead. The seed can be reset using this function, but this will only affect the thread where the function is called from, as well as any threads spawned later. If a fixed seed is needed, this function hence needs to be called prior to spawning threads, and in particlar, before calling the init_global_thread_pool() functions. Otherwise, this function throws an exception, in order to avoid potential bugs that would be hard to track down.

In a single threaded environment, this behaves identical to the usual way of (re)seeding a random engine.

Definition at line 147 of file options.hpp.

◆ seed_counter()

size_t seed_counter ( ) const

inline

Return the number of seeds used to initialize thread-local random engines.

This corresponds to the number of threads that have called random_engine().

Definition at line 178 of file options.hpp.

Member Enumeration Documentation

◆ InputReadingThreadPolicy

enum InputReadingThreadPolicy

strong

Decide how to use threads for input reading.

Enumerator

kStrict

All input reading uses the global thread pool.

This means that we do not spawn extra threads for simply I/O, which can slow down the reading, as file reading then needs to wait in the global thread queue to be processed. It however makes sure that we are not spawning any more threads on top of the global pool, which might be relevant on some systems.

kTrivialAsync

Use async threads for trivial input sources, such as simple files, but use the global thread pool for sources that need computation.

This is the default, where trivial input sources such as a simple file reading get their own thread, so that their I/O wait time does not block any computational threads. However, input sources such as gzipped files, which need decompression first, instead use the global thread pool, in order to make sure that their computation does not end up in over-subscribing the threads.

kAllAsync

All reading from input sources gets their own thread.

These threads are hence independent of the global thread pool, which can lead to oversubscribing if I/O-heavy work and computational work need to be performed at the same time. It can however be a performance optimization for programs that mostly do simple file reading, without having to synchronize their threads via the global pool.

Definition at line 299 of file options.hpp.

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

options.hpp

Detailed Description

Public Member Functions

Static Public Member Functions

Public Types

Member Function Documentation

◆ allow_file_overwriting() [1/2]

◆ allow_file_overwriting() [2/2]

◆ command_line() [1/2]

◆ command_line() [2/2]

◆ command_line_string()

◆ get()

◆ global_thread_pool()

◆ global_thread_pool_size()

◆ init_global_thread_pool() [1/2]

◆ init_global_thread_pool() [2/2]

◆ input_reading_thread_policy() [1/2]

◆ input_reading_thread_policy() [2/2]

◆ random_engine()

◆ random_seed() [1/2]

◆ random_seed() [2/2]

◆ seed_counter()

Member Enumeration Documentation

◆ InputReadingThreadPolicy