Reference documentation for deal.II version GIT relicensing-462-g03c82a14bd 2024-04-21 16:20:02+00:00
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
No Matches
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Attributes | Private Types | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | List of all members
ParameterAcceptorProxy< SourceClass > Class Template Reference

#include <deal.II/base/parameter_acceptor.h>

Inheritance diagram for ParameterAcceptorProxy< SourceClass >:
Inheritance graph

Public Member Functions

template<typename... Args>
 ParameterAcceptorProxy (const std::string &section_name, Args... args)
virtual void declare_parameters (ParameterHandler &prm) override
virtual void parse_parameters (ParameterHandler &prm) override
unsigned int get_acceptor_id () const
std::string get_section_name () const
std::vector< std::string > get_section_path () const
template<typename ParameterType >
void add_parameter (const std::string &entry, ParameterType &parameter, const std::string &documentation="", ParameterHandler &prm_=prm, const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern())
void enter_subsection (const std::string &subsection)
void leave_subsection ()
void enter_my_subsection (ParameterHandler &prm)
void leave_my_subsection (ParameterHandler &prm)
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
Subscriptor functionality

Classes derived from Subscriptor provide a facility to subscribe to this object. This is mostly used by the SmartPointer class.

void subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const
void unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const
unsigned int n_subscriptions () const
template<typename StreamType >
void list_subscribers (StreamType &stream) const
void list_subscribers () const

Static Public Member Functions

static void initialize (const std::string &filename="", const std::string &output_filename="", const ParameterHandler::OutputStyle output_style_for_output_filename=ParameterHandler::Short, ParameterHandler &prm=ParameterAcceptor::prm, const ParameterHandler::OutputStyle output_style_for_filename=ParameterHandler::DefaultStyle)
static void initialize (std::istream &input_stream, ParameterHandler &prm=ParameterAcceptor::prm)
static void clear ()
static void parse_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)
static void declare_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)
static ::ExceptionBaseExcInUse (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBaseExcNoSubscriber (std::string arg1, std::string arg2)

Public Attributes

boost::signals2::signal< void()> declare_parameters_call_back
boost::signals2::signal< void()> parse_parameters_call_back

Static Public Attributes

static ParameterHandler prm

Protected Attributes

const std::string section_name
std::vector< std::string > subsections

Private Types

using map_value_type = decltype(counter_map)::value_type
using map_iterator = decltype(counter_map)::iterator

Private Member Functions

void check_no_subscribers () const noexcept

Static Private Member Functions

static unsigned int get_next_free_id ()

Private Attributes

const unsigned int acceptor_id
std::atomic< unsigned intcounter
std::map< std::string, unsigned intcounter_map
std::vector< std::atomic< bool > * > validity_pointers
const std::type_info * object_info

Static Private Attributes

static std::mutex class_list_mutex
static std::set< ParameterAcceptor *, internal::ParameterAcceptorCompareclass_list
static const char sep = '/'
static std::mutex mutex

Detailed Description

template<class SourceClass>
class ParameterAcceptorProxy< SourceClass >

A proxy ParameterAcceptor wrapper for classes that have a static member function declare_parameters, and a non virtual parse_parameters method.

If you cannot or do not want to derive your "parameter accepting" class from ParameterAcceptor, for example if by design you are required to have a static member function declare_parameters and a member parse_parameters, or if someone has already implemented such a class for you, and only provides you with an API that you cannot modify, then you may be able to use ParameterAcceptor facilities nonetheless, by wrapping your class into ParameterAcceptorProxy.

This class implements the public interface of ParameterAcceptor, and at the same time it derives from the template class SourceClass, allowing you to register your existing SourceClass as a ParameterAcceptor class, without requiring you to explicitly derive your SourceClass from ParameterAcceptor.

An example usage is given by the following snippet of code, using Functions::ParsedFunction as an example source class:

static void initialize(const std::string &filename="", const std::string &output_filename="", const ParameterHandler::OutputStyle output_style_for_output_filename=ParameterHandler::Short, ParameterHandler &prm=ParameterAcceptor::prm, const ParameterHandler::OutputStyle output_style_for_filename=ParameterHandler::DefaultStyle)

The above snippet of code will initialize ParameterAcceptor::prm with a section "Some function", and will correctly parse and assign to the object fun the expression parsed from the file test.prm. If non-existent, the program will exit, and generate it for you (here you can see the resulting short text version of the parameter file generated with the above snippet):

# Parameter file generated with
subsection Some function
set Function constants =
set Function expression = 0
set Variable names = x,y,t

The resulting fun object, is both a ParsedFunction object and a ParameterAcceptor one, allowing you to use it as a replacement of the ParsedFunction class, with automatic declaration and parsing of parameter files.

See the tutorial program step-60 for an example on how to use this class.

Definition at line 697 of file parameter_acceptor.h.

Member Typedef Documentation

◆ map_value_type

using Subscriptor::map_value_type = decltype(counter_map)::value_type

The data type used in counter_map.

Definition at line 229 of file subscriptor.h.

◆ map_iterator

using Subscriptor::map_iterator = decltype(counter_map)::iterator

The iterator type used in counter_map.

Definition at line 234 of file subscriptor.h.

Constructor & Destructor Documentation

◆ ParameterAcceptorProxy()

template<class SourceClass >
template<typename... Args>
ParameterAcceptorProxy< SourceClass >::ParameterAcceptorProxy ( const std::string &  section_name,
Args...  args 

Default constructor. The argument section_name is forwarded to the constructor of the ParameterAcceptor class, while all other arguments are passed to the SourceClass constructor.

Definition at line 743 of file parameter_acceptor.h.

Member Function Documentation

◆ declare_parameters()

template<class SourceClass >
void ParameterAcceptorProxy< SourceClass >::declare_parameters ( ParameterHandler prm)

Overloads the ParameterAcceptor::declare_parameters function, by calling SourceClass::declare_parameters with prm as an argument.

Reimplemented from ParameterAcceptor.

Definition at line 754 of file parameter_acceptor.h.

◆ parse_parameters()

template<class SourceClass >
void ParameterAcceptorProxy< SourceClass >::parse_parameters ( ParameterHandler prm)

Overloads the ParameterAcceptor::parse_parameters function, by calling SourceClass::parse_parameters with prm as an argument.

Reimplemented from ParameterAcceptor.

Definition at line 763 of file parameter_acceptor.h.

◆ get_acceptor_id()

unsigned int ParameterAcceptor::get_acceptor_id ( ) const

Get the acceptor id of this object.

Definition at line 277 of file

◆ initialize() [1/2]

void ParameterAcceptor::initialize ( const std::string &  filename = "",
const std::string &  output_filename = "",
const ParameterHandler::OutputStyle  output_style_for_output_filename = ParameterHandler::Short,
ParameterHandler prm = ParameterAcceptor::prm,
const ParameterHandler::OutputStyle  output_style_for_filename = ParameterHandler::DefaultStyle 

Call declare_all_parameters(), read the parameters from filename (only if filename is a non-empty string), and then call parse_all_parameters().

If the parameter filename is the empty string, then no attempt to read a parameter file is done. This may be useful if you are ok with using default values, and don't want to read external files to use a class derived from ParameterAcceptor.

If output_filename is not the empty string, then we write the content that was read into the output_filename file, using the style specified in output_style_for_output_filename. The format of both input and output files are selected using the extensions of the files themselves. This can be either prm, xml, or json for the filename, and any of the supported formats for the output_filename.

If the input file does not exist, a default one with the same name is created for you following the style specified in output_style_for_filename, and an exception is thrown.

By default, the file format used to write the files is deduced from the extension of the file names. If the corresponding ParameterHandler::OutputStyle specifies a format specification, this must be compatible with the file extension, or an exception will be thrown.

If the extension is not recognized, and you do not specify a format in the corresponding ParameterHandler::OutputStyle, an assertion is thrown.

filenameInput file name
output_filenameOutput file name
output_style_for_output_filenameHow to write the output file
prmThe ParameterHandler to use
output_style_for_filenameHow to write the default input file if it does not exist

Definition at line 82 of file

◆ initialize() [2/2]

void ParameterAcceptor::initialize ( std::istream &  input_stream,
ParameterHandler prm = ParameterAcceptor::prm 

Call declare_all_parameters(), read the parameters from the input_stream in prm format, and then call parse_all_parameters().

An exception is thrown if the input_stream is invalid.

input_streamInput stream
prmThe ParameterHandler to use

Definition at line 116 of file

◆ clear()

void ParameterAcceptor::clear ( )

Clear class list and global parameter file.

Definition at line 128 of file

◆ parse_all_parameters()

void ParameterAcceptor::parse_all_parameters ( ParameterHandler prm = ParameterAcceptor::prm)

Parse the given ParameterHandler. This function enters the subsection returned by get_section_name() for each derived class, and parses all parameters that were added using add_parameter().

Definition at line 150 of file

◆ declare_all_parameters()

void ParameterAcceptor::declare_all_parameters ( ParameterHandler prm = ParameterAcceptor::prm)

Initialize the global ParameterHandler with all derived classes parameters.This function enters the subsection returned by get_section_name() for each derived class, and declares all parameters that were added using add_parameter().

Definition at line 164 of file

◆ get_section_name()

std::string ParameterAcceptor::get_section_name ( ) const

Return the section name of this class. If a name was provided at construction time, then that name is returned, otherwise it returns the demangled name of this class.

Definition at line 73 of file

◆ get_section_path()

std::vector< std::string > ParameterAcceptor::get_section_path ( ) const

Traverse all registered classes, and figure out what subsections we need to enter.

Definition at line 178 of file

◆ add_parameter()

template<typename ParameterType >
void ParameterAcceptor::add_parameter ( const std::string &  entry,
ParameterType &  parameter,
const std::string &  documentation = "",
ParameterHandler prm_ = prm,
const Patterns::PatternBase pattern = *Patterns::Tools::Convert<ParameterType>::to_pattern() 

Add a parameter in the correct path. This method forwards all arguments to the prm.add_parameter() method, after entering the correct section path. By default it uses the ParameterAcceptor::prm variable as ParameterHandler.

See the documentation of ParameterHandler::add_parameter() for more information.

Definition at line 728 of file parameter_acceptor.h.

◆ enter_subsection()

void ParameterAcceptor::enter_subsection ( const std::string &  subsection)

Add the given subsection to the global path stored in this class.

This function changes the behavior of enter_my_subsection(), by appending a new subsection to the path stored in this class.

This method can be used to split the parameters of this class into subsections, while still maintaining the general behavior of this class.

An example usage is given by the following snippet:

class MyClass : public ParameterAcceptor
: ParameterAcceptor("Main section")
add_parameter("A param", member_var);
enter_subsection("New section");
add_parameter("Another param", another_member_var);
std::vector<unsigned int> member_var = {1,2};
std::map<types::boundary_id, std::string> another_member_var;
int main()
// ParameterAcceptor::initialize()
MyClass class;
// With this call, all derived classes will have their
// parameters initialized

which will produce a parameter file organized as

subsection Main section
set A param = 1, 2
subsection New section
set Another param =

Definition at line 226 of file

◆ leave_subsection()

void ParameterAcceptor::leave_subsection ( )

Leave the subsection that was entered by calling the enter_subsection() function.

Definition at line 241 of file

◆ enter_my_subsection()

void ParameterAcceptor::enter_my_subsection ( ParameterHandler prm = ParameterAcceptor::prm)

Make sure we enter the right subsection of the given parameter.

Definition at line 251 of file

◆ leave_my_subsection()

void ParameterAcceptor::leave_my_subsection ( ParameterHandler prm = ParameterAcceptor::prm)

This function undoes what the enter_my_subsection() function did. It only makes sense if enter_my_subsection() was called on prm before this one.

Definition at line 264 of file

◆ get_next_free_id()

unsigned int ParameterAcceptor::get_next_free_id ( )

Get the next free id for this class.

Definition at line 285 of file

◆ subscribe()

void Subscriptor::subscribe ( std::atomic< bool > *const  validity,
const std::string &  identifier = "" 
) const

Subscribes a user of the object by storing the pointer validity. The subscriber may be identified by text supplied as identifier.

Definition at line 135 of file

◆ unsubscribe()

void Subscriptor::unsubscribe ( std::atomic< bool > *const  validity,
const std::string &  identifier = "" 
) const

Unsubscribes a user from the object.

The identifier and the validity pointer must be the same as the one supplied to subscribe().

Definition at line 155 of file

◆ n_subscriptions()

unsigned int Subscriptor::n_subscriptions ( ) const

Return the present number of subscriptions to this object. This allows to use this class for reference counted lifetime determination where the last one to unsubscribe also deletes the object.

Definition at line 300 of file subscriptor.h.

◆ list_subscribers() [1/2]

template<typename StreamType >
void Subscriptor::list_subscribers ( StreamType &  stream) const

List the subscribers to the input stream.

Definition at line 317 of file subscriptor.h.

◆ list_subscribers() [2/2]

void Subscriptor::list_subscribers ( ) const

List the subscribers to deallog.

Definition at line 203 of file

◆ serialize()

template<class Archive >
void Subscriptor::serialize ( Archive &  ar,
const unsigned int  version 

Read or write the data of this object to or from a stream for the purpose of serialization using the BOOST serialization library.

This function does not actually serialize any of the member variables of this class. The reason is that what this class stores is only who subscribes to this object, but who does so at the time of storing the contents of this object does not necessarily have anything to do with who subscribes to the object when it is restored. Consequently, we do not want to overwrite the subscribers at the time of restoring, and then there is no reason to write the subscribers out in the first place.

Definition at line 309 of file subscriptor.h.

◆ check_no_subscribers()

void Subscriptor::check_no_subscribers ( ) const

Check that there are no objects subscribing to this object. If this check passes then it is safe to destroy the current object. It this check fails then this function will either abort or print an error message to deallog (by using the AssertNothrow mechanism), but will not throw an exception.

Since this function is just a consistency check it does nothing in release mode.
If this function is called when there is an uncaught exception then, rather than aborting, this function prints an error message to the standard error stream and returns.

Definition at line 52 of file

Member Data Documentation

◆ declare_parameters_call_back

boost::signals2::signal<void()> ParameterAcceptor::declare_parameters_call_back

Declare parameter call back. This signal is triggered right after declare_parameters() has been called, to allow users to prepare their variables right after parameters have been declared. The default implementation is empty.

Definition at line 460 of file parameter_acceptor.h.

◆ parse_parameters_call_back

boost::signals2::signal<void()> ParameterAcceptor::parse_parameters_call_back

Parse parameter call back. This function is called at the end of parse_parameters(), to allow users to process their parameters right after they have been parsed. The default implementation is empty.

You can use this function, for example, to create a quadrature rule after you have read how many quadrature points you wanted to use from the parameter file.

Definition at line 479 of file parameter_acceptor.h.

◆ prm

ParameterHandler ParameterAcceptor::prm

The global parameter handler.

Definition at line 534 of file parameter_acceptor.h.

◆ class_list_mutex

std::mutex ParameterAcceptor::class_list_mutex

A mutex to prevent writing on the class_list set from multiple threads.

Definition at line 620 of file parameter_acceptor.h.

◆ class_list

std::set< ParameterAcceptor *, internal::ParameterAcceptorCompare > ParameterAcceptor::class_list

A set containing the address of all constructed classes of type ParameterAcceptor.

Definition at line 627 of file parameter_acceptor.h.

◆ acceptor_id

const unsigned int ParameterAcceptor::acceptor_id

The id of this specific class instance.

Definition at line 630 of file parameter_acceptor.h.

◆ sep

const char ParameterAcceptor::sep = '/'

Separator between sections.

Definition at line 635 of file parameter_acceptor.h.

◆ section_name

const std::string ParameterAcceptor::section_name

The subsection name for this class.

Definition at line 639 of file parameter_acceptor.h.

◆ subsections

std::vector<std::string> ParameterAcceptor::subsections

The subsubsections that are currently active.

Definition at line 642 of file parameter_acceptor.h.

◆ counter

std::atomic<unsigned int> Subscriptor::counter

Store the number of objects which subscribed to this object. Initially, this number is zero, and upon destruction it shall be zero again (i.e. all objects which subscribed should have unsubscribed again).

The creator (and owner) of an object is counted in the map below if HE manages to supply identification.

We use the mutable keyword in order to allow subscription to constant objects also.

This counter may be read from and written to concurrently in multithreaded code: hence we use the std::atomic class template.

Definition at line 218 of file subscriptor.h.

◆ counter_map

std::map<std::string, unsigned int> Subscriptor::counter_map

In this map, we count subscriptions for each different identification string supplied to subscribe().

Definition at line 224 of file subscriptor.h.

◆ validity_pointers

std::vector<std::atomic<bool> *> Subscriptor::validity_pointers

In this vector, we store pointers to the validity bool in the SmartPointer objects that subscribe to this class.

Definition at line 240 of file subscriptor.h.

◆ object_info

const std::type_info* Subscriptor::object_info

Pointer to the typeinfo object of this object, from which we can later deduce the class name. Since this information on the derived class is neither available in the destructor, nor in the constructor, we obtain it in between and store it here.

Definition at line 248 of file subscriptor.h.

◆ mutex

std::mutex Subscriptor::mutex

A mutex used to ensure data consistency when accessing the mutable members of this class. This lock is used in the subscribe() and unsubscribe() functions, as well as in list_subscribers().

Definition at line 271 of file subscriptor.h.

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