C++ API Reference

This reference is generated from the curated envpool/core headers used by the Add New Environment into EnvPool integration guide. It is meant to make the C++ extension surface available on Read the Docs alongside the narrative guide.

Core Data Structures

class Array

Subclassed by TArray< Dtype >

Public Functions

Array() = default

template<class Deleter> inline Array(const ShapeSpec &spec, char *data, Deleter &&deleter): Constructor an Array of shape defined by spec, with data as pointer to its raw memory. Array does not own the memory.

inline Array(const ShapeSpec &spec, char *data)

inline explicit Array(const ShapeSpec &spec): Constructor an Array of shape defined by spec. This constructor allocates and owns the memory.

template<typename ...Index> inline Array operator()(Index... index) const

Take multidimensional index into the Array.

The returned view does not extend this Array’s storage lifetime. Callers must keep the backing Array alive while using it.

inline Array operator[](int index) const: Index operator of array, takes the index along the first axis.

inline Array Slice(std::size_t start, std::size_t end) const

Take a slice at the first axis of the Array.

The returned view does not extend this Array’s storage lifetime. Callers must keep the backing Array alive while using it.

inline void Assign(const Array &value) const: Copy the content of another Array to this Array.

template<typename T, std::enable_if_t<!std::is_same_v<T, Array>, bool> = true> inline void operator=(const T &value) const: Assign to this Array a scalar value. This Array needs to have a scalar shape.

template<typename T> inline void Fill(const T &value) const: Fills this array with a scalar value of type T.

template<typename T> inline void Assign(const T *buff, std::size_t sz) const: Copy the memory starting at raw.first, to raw.first + raw.second to the memory of this Array.

inline std::size_t Shape(std::size_t dim) const: Size of axis dim.

inline const std::vector<std::size_t> &Shape() const: Shape

inline void *Data() const: Pointer to the raw memory.

inline Array Truncate(std::size_t end) const: Truncate the Array. Return a new Array that shares the same memory location but with a truncated shape.

inline void Zero() const

inline std::shared_ptr<char> SharedPtr() const

Public Members

std::size_t size

std::size_t ndim

std::size_t element_size

template<typename Dtype> class TArray : public Array 

Public Functions

TArray() = default

inline explicit TArray(const Spec<Dtype> &spec)

inline explicit TArray(const Spec<Dtype> &spec, const char *data)

template<typename A, std::enable_if_t<std::is_same_v<std::decay_t<A>, Array>, bool> = true> inline explicit TArray(A &&array)

template<typename ...Index> inline TArray operator()(Index... index) const: Take multidimensional index into the Array.

inline TArray operator[](int index) const: Index operator of array, takes the index along the first axis.

inline TArray Slice(std::size_t start, std::size_t end) const: Take a slice at the first axis of the Array.

inline void Assign(const TArray &value) const: Copy the content of another Array to this Array.

inline void Assign(const Array &value) const

template<typename T, std::enable_if_t<!std::is_same_v<T, TArray>, bool> = true> inline void operator=(const T &value) const: Assign a scalar value.

template<typename T> inline void Fill(const T &value) const: Fills this array with a scalar value of type T.

inline void Assign(const Dtype *buff, std::size_t sz) const: Copy the memory starting at raw.first, to raw.first + raw.second to the memory of this Array.

inline operator Dtype&() const

template<typename T, std::enable_if_t<!std::is_same_v<T, Dtype>, bool> = true> inline operator T() const: Cast the Array to a scalar value of type T. This Array needs to have a scalar shape.

inline TArray Truncate(std::size_t end) const: Truncate the Array. Return a new Array that shares the same memory location but with a truncated shape.

class ShapeSpec

Subclassed by Spec< D >, Spec< Container< D > >

Public Functions

ShapeSpec() = default

inline ShapeSpec(int element_size, std::vector<int> shape_vec)

inline ShapeSpec Batch(int batch_size) const

inline std::vector<std::size_t> Shape() const

Public Members

int element_size

std::vector<int> shape

template<typename D> class Spec : public ShapeSpec 

Public Types

using dtype = D 

Public Functions

inline explicit Spec(std::vector<int> &&shape)

inline explicit Spec(const std::vector<int> &shape)

inline Spec(std::vector<int> &&shape, std::tuple<dtype, dtype> &&bounds)

inline Spec(const std::vector<int> &shape, const std::tuple<dtype, dtype> &bounds)

inline Spec(std::vector<int> &&shape, std::initializer_list<dtype> bounds)

inline Spec(const std::vector<int> &shape, std::initializer_list<dtype> bounds)

inline Spec(std::initializer_list<int> shape, std::initializer_list<dtype> bounds)

inline Spec(std::vector<int> &&shape, std::tuple<std::vector<dtype>, std::vector<dtype>> &&elementwise_bounds)

inline Spec(const std::vector<int> &shape, const std::tuple<std::vector<dtype>, std::vector<dtype>> &elementwise_bounds)

inline Spec Batch(int batch_size) const

Public Members

bool is_discrete = {false}

std::tuple<dtype, dtype> bounds = {std::numeric_limits<dtype>::min(), std::numeric_limits<dtype>::max()}

std::tuple<std::vector<dtype>, std::vector<dtype>> elementwise_bounds

The compile-time dictionary helpers used by these types still live in envpool/core/dict.h and are referenced throughout Add New Environment into EnvPool.

Environment Authoring

The shared dictionaries in envpool/core/env_spec.h define the base configuration, action, and state entries that every environment family extends: common_config, common_action_spec, and common_state_spec.

template<typename EnvFns> class EnvSpec

EnvSpec function, it constructs the env spec when a Config is passed.

Subclassed by PyEnvSpec< EnvSpec >

Public Functions

inline EnvSpec()

inline explicit EnvSpec(const ConfigValues &conf)

Public Members

Config config

StateSpec state_spec

ActionSpec action_spec

template<typename EnvSpec> class Env

Single RL environment abstraction.

Public Types

using Spec = EnvSpec 

using State = Dict<typename EnvSpec::StateKeys, typename SpecToTArray<typename EnvSpec::StateSpec::Values>::Type>

using Action = Dict<typename EnvSpec::ActionKeys, typename SpecToTArray<typename EnvSpec::ActionSpec::Values>::Type>

Public Functions

inline Env(const EnvSpec &spec, int env_id)

virtual ~Env() = default

inline void SetAction(std::shared_ptr<std::vector<Array>> action_batch, int env_index)

inline void ParseAction()

inline void EnvStep(StateBufferQueue *sbq, int order, bool reset, bool force_reset)

inline virtual void Reset()

inline virtual void Step(const Action &action)

inline virtual bool IsDone()

Public Static Functions

static inline int ResolveSeed(const EnvSpec &spec, int env_id)

Pool Implementations

template<typename EnvSpec> class EnvPool

Template subclass of EnvPool, to be overridden by the real EnvPool.

Subclassed by PyEnvPool< EnvPool >

Public Types

using Spec = EnvSpec 

using State = NamedVector<typename EnvSpec::StateKeys, std::vector<Array>>

using Action = NamedVector<typename EnvSpec::ActionKeys, std::vector<Array>>

Public Functions

inline explicit EnvPool(EnvSpec spec)

virtual ~EnvPool() = default

Public Members

EnvSpec spec

template<typename Env> class AsyncEnvPool : public EnvPool<Env::Spec>

Async EnvPool

batch-action -> action buffer queue -> threadpool -> state buffer queue

ThreadPool is tailored with EnvPool, so here we don’t use the existing third_party ThreadPool (which is really slow).

Public Types

using Spec = typename Env::Spec

using Action = typename Env::Action

using State = typename Env::State

using ActionSlice = typename ActionBufferQueue::ActionSlice

Public Functions

inline explicit AsyncEnvPool(const Spec &spec)

inline ~AsyncEnvPool() override

inline void Send(const Action &action)

inline virtual void Send(const std::vector<Array> &action) override

inline virtual void Send(std::vector<Array> &&action) override

inline virtual std::vector<Array> Recv() override

inline virtual Array Render(const Array &env_ids, int width, int height, int camera_id) override

inline virtual void Reset(const Array &env_ids) override

Python Binding Helpers

template<typename EnvSpec> class PyEnvSpec : public EnvSpec<EnvFns>

Public Types

using StateSpecT = decltype(ExportSpecs(std::declval<typename EnvSpec::StateSpec>()))

using ActionSpecT = decltype(ExportSpecs(std::declval<typename EnvSpec::ActionSpec>()))

Public Functions

inline explicit PyEnvSpec(const typename EnvSpec::ConfigValues &conf)

inline StateSpecT StateSpecPy() const

inline ActionSpecT ActionSpecPy() const

Public Members

EnvSpec::ConfigValues py_config_values

Public Static Attributes

static std::vector<std::string> py_config_keys = EnvSpec::Config::AllKeys()

static std::vector<std::string> py_state_keys = EnvSpec::StateSpec::AllKeys()

static std::vector<std::string> py_action_keys = EnvSpec::ActionSpec::AllKeys()

static EnvSpec::ConfigValues py_default_config_values = EnvSpec::kDefaultConfig.AllValues()

template<typename EnvPool> class PyEnvPool : public EnvPool<EnvSpec>

Template subclass of EnvPool, to be overridden by the real EnvPool.

Public Types

using PySpec = PyEnvSpec<typename EnvPool::Spec>

Public Functions

inline explicit PyEnvPool(const PySpec &py_spec)

inline py::tuple Xla(): Get XLA functions.

inline void PySend(const std::vector<py::array> &action): py api

inline std::vector<py::array> PyRecv(): py api

inline void PyReset(const py::array &env_ids): py api

inline py::array PyRender(const py::array &env_ids, int width, int height, int camera_id)

Public Members

PySpec py_spec

Public Static Attributes

static std::vector<std::string> py_state_keys = PyEnvPool<EnvPool>::PySpec::py_state_keys

static std::vector<std::string> py_action_keys = PyEnvPool<EnvPool>::PySpec::py_action_keys