Teuchos Package Browser (Single Doxygen Collection)
Version of the Day
|
Interface for objects that can accept a ParameterList. More...
#include <Teuchos_ParameterListAcceptor.hpp>
Public Member Functions | |
virtual | ~ParameterListAcceptor () |
Destructor. More... | |
Pure virtual functions that must be overridden in subclasses | |
virtual void | setParameterList (const RCP< ParameterList > ¶mList)=0 |
Set parameters from a parameter list and return with default values. More... | |
virtual RCP< ParameterList > | getNonconstParameterList ()=0 |
Get a nonconst version of the parameter list that was set using setParameterList(). More... | |
virtual RCP< ParameterList > | unsetParameterList ()=0 |
Unset the parameter list that was set using setParameterList() . More... | |
Virtual functions with default implementation | |
virtual RCP< const ParameterList > | getParameterList () const |
Get const version of the parameter list that was set using setParameterList() . More... | |
virtual RCP< const ParameterList > | getValidParameters () const |
Return a ParameterList containing all of the valid parameters that this->setParameterList(...) will accept, along with any validators. More... | |
virtual RCP< const DependencySheet > | getDependencies () const |
Rreturn a const DependencySheet of all the dependencies that should be applied to the ParameterList returned by this->getValidParameters() . More... | |
Interface for objects that can accept a ParameterList.
Most users only need to know about two methods:
setParameterList() lets users set this object's parameters. getValidParameters() returns a default list of parameters, including any documentation and/or validators that the subclass may provide. If you call setParameterList(), implementations will fill in any missing parameters with their default values, and do validation. That's all you really need to know! If you want more details about semantics, though, please read on.
This interface does not define the semantics of calling setParametersList() twice with different lists. For example, suppose that the class SomeClass
takes two parameters:
int
parameter "Integer parameter" bool
parameter "Boolean parameter" The default value of the first is 0, and the default value of the second is false. In the following code sample, what is the final state of x's parameters?
The answer is that we can't tell without knowing more about SomeClass
. There are at least two possibilities:
"Integer parameter" is 0, and "Boolean parameter" is true "Integer parameter" is 42, and "Boolean parameter" is true
The first possibility says that the input ParameterList expresses the complete state of the object. Any missing parameters in subsequent calls get filled in with their default values. The second possibility says that the input ParameterList expresses a "delta," a difference from its current state. You must read the subclass' documentation to determine which of these it implements.
Developers who would like a simpler interface from which to inherit may prefer the subclass ParameterListAcceptorDefaultBase. That class provides default implementations of all but two of this class' methods.
It's tempting to begin setParameterList() as follows:
That's correct, but be aware that this can only be used to implement "complete state" semantics, not "delta" semantics. This is because validateParametersAndSetDefaults() fills in default values, as its name suggests.
Before ParameterList had the validation feature, many implementations of setParameterList() would use the two-argument version of ParameterList::get()
, and supply the current value of the parameter as the default if that parameter didn't exist in the input list. This implemented delta semantics. It is unclear whether implementers knew what semantics they were implementing, but that was the effect of their code.
If you want to implement delta semantics, and also want to exploit the validation feature, you have at least two options. First, you could use the validation method that does not set defaults:
and then use the two-argument version of ParameterList::get()
in the way discussed above, so that existing parameter values don't get replaced with defaults.
The second option is to keep a copy of the ParameterList from the previous call to setParameterList(). This must be a deep copy, because users might have changed parameters since then. (It is likely that they have just one ParameterList, which they change as necessary.) You may then use that list – not the result of getValidParameters() – as the input argument of validateParametersAndSetDefaults().
Definition at line 120 of file Teuchos_ParameterListAcceptor.hpp.
|
virtual |
Destructor.
Definition at line 19 of file Teuchos_ParameterListAcceptor.cpp.
|
pure virtual |
Set parameters from a parameter list and return with default values.
paramList | [in/out] On input: contains the parameters set by the client. On output: the same list, possibly filled with default values, depending on the implementation. |
Implementations of this method generally read parameters out of paramList
, and use them to modify the state or behavior of this object. Implementations may validate input parameters, and throw an exception or set an error state if any of them are invalid. "Validation
! paramList.is_null ()
this->getParameterList().get() == paramList.get()
This object "remembers" paramList
until it is "unset" using unsetParameterList(). When the input ParameterList is passed in, we assume that the client has finished setting parameters in the ParameterList. If the client changes paramList
after calling this method, this object's behavior is undefined. This is because the object may read the options from paramList
at any time. It may either do so in this method, or it may wait to read them at some later time. Users should not expect that if they change a parameter, that this object will automatically recognize the change. To change even one parameter, this method must be called again.
Implemented in Teuchos::ObjectBuilder< ObjectType >, AlgorithmA, Teuchos::ParameterListNonAcceptor, and Teuchos::Foo.
|
pure virtual |
Get a nonconst version of the parameter list that was set using setParameterList().
The returned ParameterList should be the same object (pointer equality) as the object given to setParameterList(). If setParameterList() has not yet been called on this object, the returned RCP may be null, but need not necessarily be. If unsetParameterList()
Implemented in Teuchos::ObjectBuilder< ObjectType >, AlgorithmA, Teuchos::ParameterListAcceptorDefaultBase, and Teuchos::Foo.
|
pure virtual |
Unset the parameter list that was set using setParameterList()
.
This does not undo the effect of setting the parameters via a call to setParameterList(). It merely "forgets" the RCP, so that getParameterList() and getNonconstParameterList() both return null.
this->getParameter().is_null ()
this->getNonconstParameter().is_null ()
Implemented in Teuchos::ObjectBuilder< ObjectType >, AlgorithmA, Teuchos::ParameterListAcceptorDefaultBase, and Teuchos::Foo.
|
virtual |
Get const version of the parameter list that was set using setParameterList()
.
The default implementation returns:
Reimplemented in Teuchos::ObjectBuilder< ObjectType >, AlgorithmA, Teuchos::Foo, and Teuchos::ParameterListAcceptorDefaultBase.
Definition at line 24 of file Teuchos_ParameterListAcceptor.cpp.
|
virtual |
Return a ParameterList containing all of the valid parameters that this->setParameterList(...)
will accept, along with any validators.
Implementations of setParameterList() may use the list returned by getValidParameters() to validate the input ParameterList.
The default implementation returns null
.
Reimplemented in Teuchos::FooC, Teuchos::ObjectBuilder< ObjectType >, Teuchos::FooB, Teuchos::FooA, AlgorithmA, and Teuchos::ParameterListNonAcceptor.
Definition at line 31 of file Teuchos_ParameterListAcceptor.cpp.
|
virtual |
Rreturn a const DependencySheet of all the dependencies that should be applied to the ParameterList returned by this->getValidParameters()
.
The default implementation returns Teuchos::null
.
Definition at line 37 of file Teuchos_ParameterListAcceptor.cpp.