Detailed Description

ValueProducer computes an AbstractValue output based on a ContextBase input.

This is commonly used for declaring output ports and cache entries.

It provides two functions for that purpose:

Allocate() returns new storage that is suitably typed to hold the output.
Calc() takes a context as input and writes to an output pointer.

For example, given this example calculator lambda:

std::function calc = [](const Context<T>& context, std::string* output) {
  *output = std::to_string(context.get_time());
};

We can capture it into a producer and then call it:

ValueProducer producer(calc);
std::unique_ptr<AbstractValue> storage = producer.Allocate();
const LeafContext<T> context;
producer.Calc(context, storage.get());
EXPECT_THAT(storage->get_value<std::string>(), ::testing::StartsWith("0.0"));

Sugar is provided to create ValueProducer objects from function pointers that operate on un-erased types, so that the user can ignore the details of type erasure and Context<T> downcasting. Refer to the Constructor overloads for details.

#include <drake/systems/framework/value_producer.h>

Public Types
using	AllocateCallback = std::function< std::unique_ptr< AbstractValue >()>
	Signature of a function suitable for allocating an object that can hold a value compatible with our Calc function. More...

using	CalcCallback = std::function< void(const ContextBase &, AbstractValue *)>
	Signature of a function suitable for calculating a context-dependent value, given a place to put the value. More...

Public Member Functions

ValueProducer ()

Creates an invalid object; calls to Allocate or Calc will throw. More...

~ValueProducer ()

bool is_valid () const

Returns true iff the allocate and calc callbacks are both non-null. More...

std::unique_ptr< AbstractValue > Allocate () const

Invokes the allocate function provided to the constructor. More...

void Calc (const ContextBase &context, AbstractValue *output) const

Invokes the calc function provided to the constructor. More...

Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable

ValueProducer (const ValueProducer &)=default

ValueProducer & operator= (const ValueProducer &)=default

ValueProducer (ValueProducer &&)=default

ValueProducer & operator= (ValueProducer &&)=default

Constructor overloads

Create a ValueProducer by providing it a with calculation callback and (if necessary) a way to allocate storage, in cases where the storage cannot be default constructed.

In many cases, your calculator function would be a class member function like this:

class MyClass {
  void MyCalc(const Context<T>& context, std::string* output) const {
    *output = std::to_string(context.get_time());
  }
};

and wrapping it would look like this:

MyClass my_class;

ValueProducer foo = ValueProducer(&my_class, &MyClass::MyCalc);

If the type of the output value is cheap to copy, then the function may return it by-value, instead of as an output argument:

class MyClass {
  double MyCalc(const Context<double>& context) const {
    return context.get_time();
  }
};
MyClass my_class;
ValueProducer foo = ValueProducer(&my_class, &MyClass::MyCalc);

If the type of the output is not default constructible, then you must provide ValueProducer with an example value to use for pre-allocation:

class MyClass {
  void MyCalc(const Context<T>& context, BasicVector<T>* output) const {
    output->get_mutable_value()[0] = context.get_time();
  }
};
MyClass my_class;
BasicVector<T> model_value(1);
ValueProducer foo = ValueProducer(
    &my_class, model_value, &MyClass::MyCalc);

In the rare case that you cannot provide an example value when creating the ValueProducer, you may instead provide an allocation callback. Refer to more specific documentation below for an example.

For ease of use, the constructor offers overloads to specify the allocate and calc functions.

The permitted argument types to specify Calc are:

(1) calc is a member function pointer with an output argument.
(2) calc is a member function pointer with a return value †.
(3) calc is a std::function with an output argument.
(4) calc is a std::function with a return value †.
(5) calc is a generic CalcCallback.

† Do not use (2) nor (4) unless the return value is cheap to copy.

The permitted argument types to specify Allocate are:

(a) allocate is via the default constructor.
(b) allocate is via user-supplied model_value.
(c) allocate is a member function pointer.
(d) allocate is a generic AllocateCallback.

All combinations of (1..5) x (a..d) are permitted, except for (5a) because the output type cannot be inferred from a generic CalcCallback.

All member function pointers must refer to member functions declared const.

For calc types (3) and (4), to pass bare non-member function pointer instead of a lambda, you must explicitly convert the pointer to a std::function:

void MyCalc(const Context<T>& context, std::string* output) { ... }
ValueProducer producer{std::function(&MyCalc)};

The constructors take the following arguments, in order:

The instance pointer (iff member function callback(s) are used).
The model_value example or allocate callback (may be omitted).
The calc callback (required).

If either allocate or calc is a member function pointer, then the class instance to bind must be the first argument. This instance pointer is aliased by the ValueProducer, so must outlive this object. (In practice, this happens automatically because the SomeClass instance will typically own all ValueProducer objects that call back into it.)

The model_value and allocate callback may be omitted when the OutputType is default constructible; this is the most common case. The need for a custom allocate function (i.e., options c or d, above) is extremely rare; prefer to use the default constructor (option a) or model_value (option b) in almost all cases.

Template Parameters

SomeContext	the subclass of ContextBase required by the calc callback
SomeOutput	the output type of the calc callback
SomeClass	the static type of the class to receive the callback(s)
SomeInstance	the type of the instance to receive the callback(s); must be castable into SomeClass

Exceptions

std::exception if any argument is null.

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, void(SomeClass::*calc)(const SomeContext &, SomeOutput *) const)

Overload (1a). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, const SomeOutput &model_value, void(SomeClass::*calc)(const SomeContext &, SomeOutput *) const)

Overload (1b). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, std::unique_ptr< SomeOutput >(SomeClass::*allocate)() const, void(SomeClass::*calc)(const SomeContext &, SomeOutput *) const)

Overload (1c). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, AllocateCallback allocate, void(SomeClass::*calc)(const SomeContext &, SomeOutput *) const)

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, SomeOutput(SomeClass::*calc)(const SomeContext &) const)

Overload (2a). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, const SomeOutput &model_value, SomeOutput(SomeClass::*calc)(const SomeContext &) const)

Overload (2b). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, std::unique_ptr< SomeOutput >(SomeClass::*allocate)() const, SomeOutput(SomeClass::*calc)(const SomeContext &) const)

Overload (2c). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, AllocateCallback allocate, SomeOutput(SomeClass::*calc)(const SomeContext &) const)

Overload (2d). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (std::function< void(const SomeContext &, SomeOutput *)> calc)

Overload (3a). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (const SomeOutput &model_value, std::function< void(const SomeContext &, SomeOutput *)> calc)

Overload (3b). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, std::unique_ptr< SomeOutput >(SomeClass::*allocate)() const, std::function< void(const SomeContext &, SomeOutput *)> calc)

Overload (3c). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (AllocateCallback allocate, std::function< void(const SomeContext &, SomeOutput *)> calc)

Overload (3d). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (std::function< SomeOutput(const SomeContext &)> calc)

Overload (4a). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (const SomeOutput &model_value, std::function< SomeOutput(const SomeContext &)> calc)

Overload (4b). More...

template<class SomeInstance , typename SomeClass , typename SomeContext , typename SomeOutput >

ValueProducer (const SomeInstance *instance, std::unique_ptr< SomeOutput >(SomeClass::*allocate)() const, std::function< SomeOutput(const SomeContext &)> calc)

Overload (4c). More...

template<typename SomeContext , typename SomeOutput >

ValueProducer (AllocateCallback allocate, std::function< SomeOutput(const SomeContext &)> calc)

Overload (4d). More...

template<typename SomeOutput , typename = std::enable_if_t<!std::is_convertible_v< SomeOutput, AllocateCallback>>>

ValueProducer (const SomeOutput &model_value, CalcCallback calc)

Overload (5b). More...

template<class SomeInstance , typename SomeClass , typename SomeOutput >

ValueProducer (const SomeInstance *instance, std::unique_ptr< SomeOutput >(SomeClass::*allocate)() const, CalcCallback calc)

Overload (5c). More...

ValueProducer (AllocateCallback allocate, CalcCallback calc)

Overload (5d). More...

Static Public Member Functions
static void	NoopCalc (const ContextBase &, AbstractValue *)
	This static function is provided for users who need an empty CalcCallback. More...

Member Typedef Documentation

◆ AllocateCallback

using AllocateCallback = std::function<std::unique_ptr<AbstractValue>()>

Signature of a function suitable for allocating an object that can hold a value compatible with our Calc function.

The result is always returned as an AbstractValue but must contain the correct concrete type.

◆ CalcCallback

using CalcCallback = std::function<void(const ContextBase&, AbstractValue*)>

Signature of a function suitable for calculating a context-dependent value, given a place to put the value.

The function may presume that the storage pointed to by the second argument will be of the proper type (as returned by an AllocateCallback), but should not presume that the storage has been initialized with any particular value; the function should always fully overwrite the output storage with a new value.

Constructor & Destructor Documentation

◆ ValueProducer() [1/22]

ValueProducer ( const ValueProducer & )

default

◆ ValueProducer() [2/22]

ValueProducer ( ValueProducer && )

default

◆ ValueProducer() [3/22]

ValueProducer ( )

Creates an invalid object; calls to Allocate or Calc will throw.

◆ ValueProducer() [4/22]

ValueProducer	(	const SomeInstance *	instance,
		void(SomeClass::)(const SomeContext &, SomeOutput ) const	calc
	)

Overload (1a).

This is the best choice. Refer to the Constructor overloads for details.

◆ ValueProducer() [5/22]

ValueProducer	(	const SomeInstance *	instance,
		const SomeOutput &	model_value,
		void(SomeClass::)(const SomeContext &, SomeOutput ) const	calc
	)

Overload (1b).

This is the second-best choice. Refer to the Constructor overloads for details.

◆ ValueProducer() [6/22]

ValueProducer	(	const SomeInstance *	instance,
		std::unique_ptr< SomeOutput >(SomeClass::*)() const	allocate,
		void(SomeClass::)(const SomeContext &, SomeOutput ) const	calc
	)

Overload (1c).

Refer to the Constructor overloads for details.

◆ ValueProducer() [7/22]

ValueProducer	(	const SomeInstance *	instance,
		AllocateCallback	allocate,
		void(SomeClass::)(const SomeContext &, SomeOutput ) const	calc
	)

◆ ValueProducer() [8/22]

ValueProducer	(	const SomeInstance *	instance,
		SomeOutput(SomeClass::*)(const SomeContext &) const	calc
	)

Overload (2a).

Refer to the Constructor overloads for details.

◆ ValueProducer() [9/22]

ValueProducer	(	const SomeInstance *	instance,
		const SomeOutput &	model_value,
		SomeOutput(SomeClass::*)(const SomeContext &) const	calc
	)

Overload (2b).

Refer to the Constructor overloads for details.

◆ ValueProducer() [10/22]

ValueProducer	(	const SomeInstance *	instance,
		std::unique_ptr< SomeOutput >(SomeClass::*)() const	allocate,
		SomeOutput(SomeClass::*)(const SomeContext &) const	calc
	)

Overload (2c).

Refer to the Constructor overloads for details.

◆ ValueProducer() [11/22]

ValueProducer	(	const SomeInstance *	instance,
		AllocateCallback	allocate,
		SomeOutput(SomeClass::*)(const SomeContext &) const	calc
	)

Overload (2d).

Refer to the Constructor overloads for details.

◆ ValueProducer() [12/22]

ValueProducer ( std::function< void(const SomeContext &, SomeOutput *)> calc )

explicit

Overload (3a).

Refer to the Constructor overloads for details.

◆ ValueProducer() [13/22]

ValueProducer	(	const SomeOutput &	model_value,
		std::function< void(const SomeContext &, SomeOutput *)>	calc
	)

Overload (3b).

Refer to the Constructor overloads for details.

◆ ValueProducer() [14/22]

ValueProducer	(	const SomeInstance *	instance,
		std::unique_ptr< SomeOutput >(SomeClass::*)() const	allocate,
		std::function< void(const SomeContext &, SomeOutput *)>	calc
	)

Overload (3c).

Refer to the Constructor overloads for details.

◆ ValueProducer() [15/22]

ValueProducer	(	AllocateCallback	allocate,
		std::function< void(const SomeContext &, SomeOutput *)>	calc
	)

Overload (3d).

Refer to the Constructor overloads for details.

◆ ValueProducer() [16/22]

ValueProducer ( std::function< SomeOutput(const SomeContext &)> calc )

explicit

Overload (4a).

Refer to the Constructor overloads for details.

◆ ValueProducer() [17/22]

ValueProducer	(	const SomeOutput &	model_value,
		std::function< SomeOutput(const SomeContext &)>	calc
	)

Overload (4b).

Refer to the Constructor overloads for details.

◆ ValueProducer() [18/22]

ValueProducer	(	const SomeInstance *	instance,
		std::unique_ptr< SomeOutput >(SomeClass::*)() const	allocate,
		std::function< SomeOutput(const SomeContext &)>	calc
	)

Overload (4c).

Refer to the Constructor overloads for details.

◆ ValueProducer() [19/22]

ValueProducer	(	AllocateCallback	allocate,
		std::function< SomeOutput(const SomeContext &)>	calc
	)

Overload (4d).

Refer to the Constructor overloads for details.

◆ ValueProducer() [20/22]

ValueProducer	(	const SomeOutput &	model_value,
		CalcCallback	calc
	)

Overload (5b).

Refer to the Constructor overloads for details.

◆ ValueProducer() [21/22]

ValueProducer	(	const SomeInstance *	instance,
		std::unique_ptr< SomeOutput >(SomeClass::*)() const	allocate,
		CalcCallback	calc
	)

Overload (5c).

Refer to the Constructor overloads for details.

◆ ValueProducer() [22/22]

ValueProducer	(	AllocateCallback	allocate,
		CalcCallback	calc
	)

Overload (5d).

Refer to the Constructor overloads for details.

◆ ~ValueProducer()

~ValueProducer ( )

Member Function Documentation

◆ Allocate()

std::unique_ptr<AbstractValue> Allocate ( ) const

Invokes the allocate function provided to the constructor.

Exceptions

std::exception if is_valid() is false.

◆ Calc()

void Calc	(	const ContextBase &	context,
		AbstractValue *	output
	)		const

Invokes the calc function provided to the constructor.

Exceptions

std::exception if is_valid() is false.

◆ is_valid()

bool is_valid ( ) const

Returns true iff the allocate and calc callbacks are both non-null.

(The only way they can be null is if the ValueProducer was default constructed or moved from.)

◆ NoopCalc()

static void NoopCalc	(	const ContextBase &	,
		AbstractValue *
	)

static

This static function is provided for users who need an empty CalcCallback.

Passing &ValueProducer::NoopCalc as ValueProducer's last constructor argument will create a function that does not compute anything, but can still allocate.

◆ operator=() [1/2]

ValueProducer& operator= ( const ValueProducer & )

default

◆ operator=() [2/2]

ValueProducer& operator= ( ValueProducer && )

default

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

drake/systems/framework/value_producer.h

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Typedef Documentation

◆ AllocateCallback

◆ CalcCallback

Constructor & Destructor Documentation

◆ ValueProducer() [1/22]

◆ ValueProducer() [2/22]

◆ ValueProducer() [3/22]

◆ ValueProducer() [4/22]

◆ ValueProducer() [5/22]

◆ ValueProducer() [6/22]

◆ ValueProducer() [7/22]

◆ ValueProducer() [8/22]

◆ ValueProducer() [9/22]

◆ ValueProducer() [10/22]

◆ ValueProducer() [11/22]

◆ ValueProducer() [12/22]

◆ ValueProducer() [13/22]

◆ ValueProducer() [14/22]

◆ ValueProducer() [15/22]

◆ ValueProducer() [16/22]

◆ ValueProducer() [17/22]

◆ ValueProducer() [18/22]

◆ ValueProducer() [19/22]

◆ ValueProducer() [20/22]

◆ ValueProducer() [21/22]

◆ ValueProducer() [22/22]

◆ ~ValueProducer()

Member Function Documentation

◆ Allocate()

◆ Calc()

◆ is_valid()

◆ NoopCalc()

◆ operator=() [1/2]

◆ operator=() [2/2]