#include <geogram/basic/environment.h>

Inheritance diagram for GEO::Environment:

Public Member Functions
virtual bool	add_environment (Environment *env)
	Adds a child environment. More...

bool	has_value (const std::string &name) const
	Tests if a variable exists. More...

virtual bool	get_value (const std::string &name, std::string &value) const
	Retrieves the value of a variable. More...

std::string	get_value (const std::string &name) const
	Retrieves the value of a variable. More...

virtual bool	set_value (const std::string &name, const std::string &value)
	Sets a variable value. More...

virtual Environment *	find_environment (const std::string &name)
	Finds the environment that declares a variable as a local name. More...

virtual bool	add_observer (const std::string &name, VariableObserver *observer)
	Attaches an observer to a variable. More...

virtual bool	remove_observer (const std::string &name, VariableObserver *observer)
	Detaches an observer from a variable. More...

virtual bool	notify_observers (const std::string &name, bool recursive=false)
	Notifies observers. More...

Public Member Functions inherited from GEO::Counted
void	ref () const
	Increments the reference count. More...

void	unref () const
	Decrements the reference count. More...

bool	is_shared () const
	Check if the object is shared. More...

int	nb_refs () const
	Gets the number of references that point to this object. More...

Static Public Member Functions
static Environment *	instance ()
	Gets the root environment. More...

static void	terminate ()
	Cleans up the environment. More...

Static Public Member Functions inherited from GEO::Counted
static void	ref (const Counted *counted)
	Increments the reference count. More...

static void	unref (const Counted *counted)
	Decrements the reference count. More...

Protected Member Functions
	~Environment () override
	Environment destructor. More...

virtual bool	get_local_value (const std::string &name, std::string &value) const =0
	Retrieves a variable value locally. More...

virtual bool	set_local_value (const std::string &name, const std::string &value)=0
	Sets a variable value locally. More...

bool	notify_observers (const std::string &name, const std::string &value, bool recursive)
	Notifies observers. More...

bool	notify_local_observers (const std::string &name, const std::string &value)
	Notifies local observers. More...

Protected Member Functions inherited from GEO::Counted
	Counted ()
	Creates a reference counted object. More...

virtual	~Counted ()
	Destroys a reference counted object. More...

Detailed Description

Application environment.

Environment is a flexible framework for storing and retrieving application properties. Most important client functions are:

get_value() to retrieve a property
set_value() to store a property

By default, the framework provides a single root Environment that can be accessed with function instance(). This root environment uses a dictionary for storing application properties as name-value pairs.

But developers can define custom Environment classes to access properties differently. For this, the custom Environment classes must reimplement low-level access functions get_local_value() and set_local_value(). For instance, one can redefine low-level functions to:

access properties in a file database
access properties as system environment variables (see SystemEnvironment)
expose/control a software module configuration:
- get_local_value() exposes the module configuration as properties
- set_local_value() allows to control the module configuration through properties.
This technique is widely used in Vorpaline, for instance:
- Process has a dedicated environment to control Process configuration (multithreading, FPE, ...)
- Logger also has a dedicated environment to configure the Logger behavior, allowed features, ...

Plugging custom Environments in the framework is as simple as adding the custom Environment as a child of the root Environment with function add_environment(). Setting a property in an environment affects this environment locally only if no child environment can store the property. Similarily, retrieving a property from an environment first checks if the property exists locally, then in all child environments.

In addition, the Environment framework provides a mechanism for being notified when a property is modified: VariableObservers can be attached to specific properties to capture modifications of their value (for more details see VariableObserver).

Definition at line 211 of file environment.h.

Constructor & Destructor Documentation

◆ ~Environment()

GEO::Environment::~Environment ( )

overrideprotected

Environment destructor.

This deletes all the child environments, but it does not delete the variable observers.

Member Function Documentation

◆ add_environment()

virtual bool GEO::Environment::add_environment ( Environment * env )

virtual

Adds a child environment.

Environment env is added as a child of this environment which takes ownership of env. The child environment will be deleted when this environment is deleted.

Parameters

[in] env the child environment

Return values

true	if the child has been successfully added
false	otherwise

◆ add_observer()

virtual bool GEO::Environment::add_observer	(	const std::string &	name,
		VariableObserver *	observer
	)

virtual

Attaches an observer to a variable.

Adds observer observer to the list of observers attached to variable name. If the observer is already attached to the variable, the function calls abort(). The environment does not take ownership of the observer, it is the responsibility of the caller to delete all the variable observers added to an Environment.

Parameters

[in]	name	the name of the variable
[in]	observer	a variable observer to add

Return values

true	if `observer` has been successfully added
false	otherwise

◆ find_environment()

virtual Environment* GEO::Environment::find_environment ( const std::string & name )

virtual

Finds the environment that declares a variable as a local name.

Parameters

[in] name the name of the variable

Returns: a pointer to the Environment that has name as a local variable, or nullptr if no such environment exists

◆ get_local_value()

virtual bool GEO::Environment::get_local_value	(	const std::string &	name,
		std::string &	value
	)		const

protectedpure virtual

Retrieves a variable value locally.

This function is used internally. It searches variable name locally and stores its value in the output string value.

Parameters

[in]	name	the name of the variable
[out]	value	is set the variable value if it was found locally.

Return values

true	if the variable was found
false	if not

Note: This function must be reimplemented in derived custom environments.

Implemented in GEO::ImageLibrary, GEO::Logger, and GEO::SystemEnvironment.

◆ get_value() [1/2]

std::string GEO::Environment::get_value ( const std::string & name ) const

Retrieves the value of a variable.

This is a variant of get_value(name, value) that returns the variable value directly it it exists. If the variable is not found, then the function calls abort().

Parameters

[in] name the name of the variable

Returns: the variable value if it exists.

◆ get_value() [2/2]

virtual bool GEO::Environment::get_value	(	const std::string &	name,
		std::string &	value
	)		const

virtual

Retrieves the value of a variable.

Searches variable name and stores its value in the output string value. The function first checks if the variable exists locally, then in all child environments recursively.

Parameters

[in]	name	the name of the variable
[out]	value	is set the variable value if it was found either locally or in a child environment.

Return values

true	if the variable was found
false	otherwise

◆ has_value()

bool GEO::Environment::has_value ( const std::string & name ) const

Tests if a variable exists.

Parameters

[in] name the name of the variable

Return values

true	if the variable exists
false	otherwise

◆ instance()

static Environment* GEO::Environment::instance ( )

static

Gets the root environment.

If the root environment does not yet exists, it is created on the fly.

Returns: A pointer to the root environment

◆ notify_local_observers()

bool GEO::Environment::notify_local_observers	(	const std::string &	name,
		const std::string &	value
	)

protected

Notifies local observers.

This function is used internally. It notifies the observers attached to variable name in this environment, passing them the modified value value. Observers in child environments are not notified.

Parameters

[in]	name	the name of the variable
[in]	value	the modified value

Returns: true

◆ notify_observers() [1/2]

virtual bool GEO::Environment::notify_observers	(	const std::string &	name,
		bool	recursive = `false`
	)

virtual

Notifies observers.

This notifies the observers attached to variable name in this environment, passing them the current value of the variable. If recursive is set to true, then the function recursively notifies observers in the child contexts.

Parameters

[in]	name	the name of the variable
[in]	recursive	if `true`, notifies observers in the child contexts. This is `false` by default.

Returns: true

◆ notify_observers() [2/2]

bool GEO::Environment::notify_observers	(	const std::string &	name,
		const std::string &	value,
		bool	recursive
	)

protected

Notifies observers.

This function is used internally. It notifies the observers attached to variable name in this environment, passing them the modified value value. If recursive is true, then the function recursively notifies observers in the child contexts.

Parameters

[in]	name	the name of the variable
[in]	value	the modified value
[in]	recursive	if `true`, notifies observers in the child contexts.

Returns: true

◆ remove_observer()

virtual bool GEO::Environment::remove_observer	(	const std::string &	name,
		VariableObserver *	observer
	)

virtual

Detaches an observer from a variable.

Removes observer observer from the list of observers attached to variable name. If the observer is not attached to the variable, the function calls abort(). The environment does not delete the removed observer, it is the responsibility of the caller to delete all the variable observers added to an Environment.

Parameters

[in]	name	the name of the variable
[in]	observer	a variable observer to remove

Return values

true	if `observer` has been successfully removed
false	otherwise

◆ set_local_value()

virtual bool GEO::Environment::set_local_value	(	const std::string &	name,
		const std::string &	value
	)

protectedpure virtual

Sets a variable value locally.

This function is used internally. It sets the variable named name to the given value locally.

Parameters

[in]	name	the name of the variable
[in]	value	the value of the variable

Return values

true	if the variable was successfully added locally
false	otherwise

Note: This function must be reimplemented in derived custom environments.

Implemented in GEO::ImageLibrary, GEO::Logger, and GEO::SystemEnvironment.

◆ set_value()

virtual bool GEO::Environment::set_value	(	const std::string &	name,
		const std::string &	value
	)

virtual

Sets a variable value.

Sets the variable named name to the given value. The function first visits all child environments recursively until one of them accepts the variable. If no child environment can store the variable, the variable is set locally in this environment. If a variable is set in an environment, all the variable observers are notified, starting from the modified environment up to the root environment.

Parameters

[in]	name	the name of the variable
[in]	value	the value of the variable

Return values

true	if the variable was successfully added, either locally or in a child environment.
false	otherwise

◆ terminate()

static void GEO::Environment::terminate ( )

static

Cleans up the environment.

This destroys the whole root Environment hierarchy.

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

geogram/basic/environment.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~Environment()

Member Function Documentation

◆ add_environment()

◆ add_observer()

◆ find_environment()

◆ get_local_value()

◆ get_value() [1/2]

◆ get_value() [2/2]

◆ has_value()

◆ instance()

◆ notify_local_observers()

◆ notify_observers() [1/2]

◆ notify_observers() [2/2]

◆ remove_observer()

◆ set_local_value()

◆ set_value()

◆ terminate()