carb::launcher::EnvCollector

Defined in carb/launcher/LauncherUtils.h

class EnvCollector

A simple environment variable collector helper class.

This provides a way to collect a set of environment variables and their values for use in ILauncher::launchProcess(). Each variable in the table will be unique. Attempting to add a variable multiple times will simply replace any previous value. Specifying a variable without a value will remove it from the table. Values for variables may be specified in any primitive integer or floating point type as well as string values. Once all desired variables have been collected into the object, a Unix style environment table can be retrieved with getEnv(). and the could with getCount(). The order of the variables in the environment block will be undefined.

The basic usage of this is to create a new object, add one or more variables and their values (of various types) using the various add() or ‘+=’ operators, the retrieve the Unix style environment block with getEnv() to assign to LaunchDesc::env, and getCount() to assign to LaunchDesc::envCount. This environment block is then passed through the launch descriptor to ILauncher::launchProcess(). Copy and move constructors are also provided to make it easier to assign and combine other environment lists.

The calling process’s current environment can also be added using the add() function without any arguments. This can be used to allow a child process to explicitly inherit the parent process’s environment block while also adding other variables or changing existing ones.

On Windows all environment variable names used in this object are treated as case insensitive. All values set set for the variables will be case preserving. This matches Windows’ native behavior in handling environment variables. If multiple casings are used in specifying the variable name when modifying any given variable, the variable’s name will always keep the casing from when it was first added. Later changes to that variable regardless of the casing will only modify the variable’s value.

On Linux, all environment variable names used in this object are treated as case sensitive. All values set for the variables will be case preserving. This matches Linux’s native behavior in handling environment variables. It is the caller’s responsibility to ensure the proper casing is used when adding or modifying variables. Failure to match the case of an existing variable for example will result in two variables with the same name but different casing being added. This can be problematic for example when attempting to modify a standard variable such as “PATH” or “LD_LIBRARY_PATH”.

Also note that using this class does not affect or modify the calling process’s environment variables in any way. This only collects variables and their values in a format suitable for setting as a child process’s new environment.

This helper class is not thread safe. It is the caller’s responsibility to ensure thread safe access to objects of this class if needed.

Public Functions

EnvCollector() = default

inline EnvCollector(const EnvCollector &rhs)

Copy constructor: copies another environment collector object into this one.

Parameters: rhs – [in] The other environment collector object whose contents will be copied into this one. This other object will not be modified.

inline EnvCollector(EnvCollector &&rhs)

Move constructor: moves the contents of an environment collector object into this one.

Parameters: rhs – [in] The other environment collector object whose contents will be moved into this one. Upon return, this other object will be reset to an empty state.

inline ~EnvCollector()

inline void clear()

Clears out this environment block object.

Remark

This clears out this environment block object. Any existing variables and their values will be lost and the object will be reset to its default constructed state for reuse.

Returns: No return value.

inline const char *const *getEnv()

Retrieves the Unix style environment block representing the variables in this object.

Remark

This retrieves the Unix style environment block for this object. The environment block object is owned by this object and should not be freed or deleted. The returned block will be valid until this object is destroyed or until getEnv() is called again. If the caller needs to keep a copy of the returned environment block object, the caller must perform a deep copy on the returned object. This task is out of the scope of this object and is left as an exercise for the caller.

Returns: A Unix style environment block. This will be an array of string pointers. The last entry in the array will always be a nullptr string. This can be used to count the length of the environment block without needing to explicitly pass in its size as well.
Returns: nullptr if the buffer for the environment block could not be allocated.

inline size_t getCount() const

Retrieves the number of unique variables in the environment block.

Returns: The total number of unique variables in this environment block.
Returns: 0 if this environment block object is empty.

inline EnvCollector &operator=(const EnvCollector &rhs)

Copy assignment operator.

Parameters: rhs – [in] The environment collector object to copy from. This object will receive a copy of all the variables currently listed in the rhs environment collector object. The rhs object will not be modified.
Returns: A reference to this object suitable for chaining other operators or calls.

inline EnvCollector &operator=(EnvCollector &&rhs)

Move assignment operator.

Parameters: rhs – [inout] The argument collector object to move from. This object will steal all arguments from rhs and will clear out the other object before returning.
Returns: A reference to this object suitable for chaining other operators or calls.

inline bool operator==(const EnvCollector &rhs)

Compare this object to another argument collector object for equality.

Parameters: rhs – [in] The argument collector object to compare to this one.
Returns: true if the two objects contain the same list of arguments. Note that each object must contain the same arguments in the same order in order for them to match.
Returns: false if the argument lists in the two objects differ.

inline bool operator!=(const EnvCollector &rhs)

Compare this object to another argument collector object for inequality.

Parameters: rhs – [in] The argument collector object to compare to this one.
Returns: true if the two objects contain a different list of arguments. Note that each object must contain the same arguments in the same order in order for them to match. If either the argument count differs or the order of the arguments differs, this will succeed.
Returns: false if the argument lists in the two objects match.

inline bool operator!()

Tests whether this argument collector is empty.

Returns: true if this argument collector object is empty.
Returns: false if argument collector has at least one argument in its list.

inline operator bool()

Tests whether this argument collector is non-empty.

Returns: true if argument collector has at least one argument in its list.
Returns: false if this argument collector object is empty.

inline EnvCollector &add(const char *name, const char *value)

Adds a new environment variable by name and value.

Remark

These functions allow various combinations of name and value types to be used to add new environment variables to this object. Values may be set as strings, integers, or floating point values.

Parameters

name – [in] The name of the environment variable to add or replace. This may not be an empty string or nullptr, and should not contain an ‘=’ except as the first character.
value – [in] The value to assign to the variable name. This may be nullptr or an empty string to add a variable with no value.

Returns

A reference to this object suitable for chaining multiple calls.

inline EnvCollector &add(const std::string &name, const std::string &value)

Adds a new environment variable by name and value.

Remark

These functions allow various combinations of name and value types to be used to add new environment variables to this object. Values may be set as strings, integers, or floating point values.

Parameters

name – [in] The name of the environment variable to add or replace. This may not be an empty string or nullptr, and should not contain an ‘=’ except as the first character.
value – [in] The value to assign to the variable name. This may be nullptr or an empty string to add a variable with no value.

Returns

A reference to this object suitable for chaining multiple calls.

inline EnvCollector &add(const std::string &name, const char *value)

Adds a new environment variable by name and value.

Remark

These functions allow various combinations of name and value types to be used to add new environment variables to this object. Values may be set as strings, integers, or floating point values.

Parameters

name – [in] The name of the environment variable to add or replace. This may not be an empty string or nullptr, and should not contain an ‘=’ except as the first character.
value – [in] The value to assign to the variable name. This may be nullptr or an empty string to add a variable with no value.

Returns

A reference to this object suitable for chaining multiple calls.

inline EnvCollector &add(const char *name, const std::string &value)

Adds a new environment variable by name and value.

Remark

These functions allow various combinations of name and value types to be used to add new environment variables to this object. Values may be set as strings, integers, or floating point values.

Parameters

name – [in] The name of the environment variable to add or replace. This may not be an empty string or nullptr, and should not contain an ‘=’ except as the first character.
value – [in] The value to assign to the variable name. This may be nullptr or an empty string to add a variable with no value.

Returns

A reference to this object suitable for chaining multiple calls.

inline EnvCollector &add(const char *name, uint8_t value)

Adds a new name and primitive value to this environment collector object.

Parameters

name – [in] The name of the new environment variable to be added. This may not be nullptr or an empty string.
value – [in] The primitive numerical value to set as the environment variable’s value. This will be converted to a string before adding to the collector.

Returns