JeVois  1.0
JeVois Smart Embedded Machine Vision Toolkit
ParameterImpl.H
Go to the documentation of this file.
1 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
2 //
3 // JeVois Smart Embedded Machine Vision Toolkit - Copyright (C) 2016 by Laurent Itti, the University of Southern
4 // California (USC), and iLab at USC. See http://iLab.usc.edu and http://jevois.org for information about this project.
5 //
6 // This file is part of the JeVois Smart Embedded Machine Vision Toolkit. This program is free software; you can
7 // redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software
8 // Foundation, version 2. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
9 // without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
10 // License for more details. You should have received a copy of the GNU General Public License along with this program;
11 // if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
12 //
13 // Contact information: Laurent Itti - 3641 Watt Way, HNB-07A - Los Angeles, CA 90089-2520 - USA.
14 // Tel: +1 213 740 3527 - itti@pollux.usc.edu - http://iLab.usc.edu - http://jevois.org
15 // ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////
16 /*! \file */
17 
18 // This code is inspired by the Neuromorphic Robotics Toolkit (http://nrtkit.org)
19 
20 #pragma once
21 
22 #include <jevois/Util/Demangle.H>
23 
24 // ######################################################################
26  itsFrozen(false), itsVirgin(true)
27 { }
28 
29 // ######################################################################
31 {
32  // unlock the mutex that was locked by Parameter<T> destructor as destroying a locked mutex is evil
33  itsMutex.unlock();
34 }
35 
36 // ######################################################################
38 { itsFrozen = true; }
39 
40 // ######################################################################
42 { itsFrozen = false; }
43 
44 // ######################################################################
45 template <typename T> inline
47  jevois::ParameterBase(), itsCallback(), itsVal(def.defaultValue()), itsDef(def)
48 { }
49 
50 // ######################################################################
51 template <typename T> inline
53 {
54  // Get a unique lock into our mutex, to ensure all get(), callbacks, etc are done before we die:
55  itsMutex.lock(); // keep us locked up into oblivion, base destructor will unlock at the last moment
56 }
57 
58 // ######################################################################
59 template <typename T> inline
60 std::string const & jevois::ParameterCore<T>::name() const
61 { return itsDef.name(); }
62 
63 // ######################################################################
64 template <typename T> inline
66 {
67  jevois::Component const * comp = owner();
68  if (comp) return comp->descriptor() + ':' + itsDef.name(); else return itsDef.name();
69 }
70 
71 // ######################################################################
72 template <typename T> inline
74 {
75  boost::shared_lock<boost::shared_mutex> lck(itsMutex);
76  return itsVal;
77 }
78 
79 // ######################################################################
80 template <typename T> inline
81 void jevois::ParameterCore<T>::setCallback(std::function<void(T const &)> cb)
82 {
83  boost::unique_lock<boost::shared_mutex> lck(itsMutex);
84  itsCallback = cb;
85 }
86 
87 // ######################################################################
88 template <typename T> inline
89 void jevois::ParameterCore<T>::set(T const & newVal)
90 {
91  boost::upgrade_lock<boost::shared_mutex> lck(itsMutex);
92 
93  // If we are frozen, reject the change:
94  if (itsFrozen)
95  {
96  std::ostringstream os;
97  os << descriptor() << ": Provided value [" << newVal << "] rejected because Parameter is frozen";
98  throw std::range_error(os.str());
99  }
100 
101 
102  // Is the value authorized, depending on the type of valid values we have:
103  if (itsDef.itsValidValuesSpec->checkValueValidity(newVal) == false)
104  {
105  std::ostringstream os;
106  os << descriptor() << ": Provided value [" << newVal << "] not valid according to specification "
107  << itsDef.itsValidValuesSpec->str();
108  throw std::range_error(os.str());
109  }
110 
111  // If we have a callback, see whether it likes this change:
112  if (itsCallback)
113  {
114  try { itsCallback(newVal); }
115  catch (std::exception const & e)
116  {
117  std::ostringstream os;
118  os << descriptor() << ": Provided value [" << newVal << "] rejected by callback with reason [" << e.what() << ']';
119  throw std::range_error(os.str());
120  }
121  catch (...)
122  {
123  std::ostringstream os;
124  os << descriptor() << ": Provided value [" << newVal << "] rejected by callback with unknown reason";
125  throw std::range_error(os.str());
126  }
127 
128  // We have been set at least once now:
129  itsVirgin = false;
130  }
131 
132  // If we made it through, all is ok. Change the value:
133  {
134  boost::upgrade_to_unique_lock<boost::shared_mutex> ulock(lck);
135  itsVal = newVal;
136  }
137 }
138 
139 // ######################################################################
140 template <typename T> inline
141 void jevois::ParameterCore<T>::strset(std::string const & valstring)
142 { jevois::ParameterCore<T>::set(jevois::detail::paramValFromString<T>(valstring, this)); }
143 
144 // ######################################################################
145 template <typename T> inline
146 std::string const jevois::ParameterCore<T>::strget() const
148 
149 // ######################################################################
150 template <typename T> inline
152 {
153  boost::unique_lock<boost::shared_mutex> ulck(itsMutex);
154  itsVal = def.defaultValue();
155  *(const_cast<jevois::ParameterDef<T> *>(& itsDef)) = def;
156 }
157 
158 // ######################################################################
159 template <typename T> inline
161 {
162  boost::shared_lock<boost::shared_mutex> _(itsMutex);
163 
164  // If we have a callback, call it with our current value:
165  if (itsCallback && itsVirgin)
166  {
167  try { itsCallback(itsVal); }
168  catch (std::exception const & e)
169  {
170  std::ostringstream os;
171  os << descriptor() << ": Value [" << itsVal << "] rejected by callback with reason [" << e.what() << ']';
172  throw std::range_error(os.str());
173  }
174  catch (...)
175  {
176  std::ostringstream os;
177  os << descriptor() << ": Value [" << itsVal << "] rejected by callback with unknown reason";
178  throw std::range_error(os.str());
179  }
180  }
181 }
182 
183 // ######################################################################
184 template <typename T> inline
186 {
188 
189  boost::shared_lock<boost::shared_mutex> lck(itsMutex);
190 
191  ps.descriptor = descriptor();
192  ps.name = itsDef.name();
193  ps.description = itsDef.description();
194  ps.valuetype = jevois::demangledName<T>();
195  ps.defaultvalue = itsDef.defaultValueString();
196  ps.value = strget();
197  ps.validvalues = itsDef.validValuesString();
198  ps.category = itsDef.category().name;
199  ps.categorydescription = itsDef.category().description;
200  ps.frozen = itsFrozen;
201 
202  return ps;
203 }
std::string const paramStringFromVal(T const &val, jevois::ParameterBase const *param)
std::string name
Plain name of the parameter.
Definition: Parameter.H:90
T const defaultValue() const
Get the default value that was specified for this Parameter definition.
std::string validvalues
Description of the parameter's valid values specification, as a string.
Definition: Parameter.H:105
std::string description
Description of the parameter.
Definition: Parameter.H:93
A changeable parameter for a Component, core class.
Definition: Parameter.H:183
void unFreeze()
Unfreeze this parameter, it becomes read-write and will show up in the help message.
Definition: ParameterImpl.H:41
virtual std::string const strget() const override
Get the value as a string representation of it.
std::string descriptor
Descriptor. This is the name of the parameter, qualified by a chain of component names.
Definition: Parameter.H:87
ParameterBase()
Constructor.
Definition: ParameterImpl.H:25
ParameterSummary provides a summary about a parameter.
Definition: Parameter.H:83
std::string value
Current value of the parameter, as a string.
Definition: Parameter.H:102
std::string defaultvalue
Default value of the parameter, as a string.
Definition: Parameter.H:99
virtual std::string const & name() const override
Get the parameter name.
Definition: ParameterImpl.H:60
A Parameter Definition.
Definition: ParameterDef.H:88
A component of a model hierarchy.
Definition: Component.H:176
virtual void strset(std::string const &valstring) override
Set the value from a string representation of it.
void changeParameterDef(ParameterDef< T > const &def)
Change the ParameterDef of this parameter.
std::string valuetype
Parameter value type, as a string.
Definition: Parameter.H:96
std::string descriptor() const
Get our full descriptor (including all parents) as [Instancename]:[...]:[...].
Definition: Component.C:264
virtual ParameterSummary const summary() const override
Get summary info about this parameter.
virtual std::string descriptor() const override
Get the parameter fully-qualified name, aka descriptor.
Definition: ParameterImpl.H:65
T get() const
Get the value of this Parameter.
Definition: ParameterImpl.H:73
bool frozen
Flag that indicates whether parameter is frozen.
Definition: Parameter.H:114
void freeze()
Freeze this parameter, it becomes read-only and will not show up in the help message.
Definition: ParameterImpl.H:37
Base class for Parameter.
Definition: Parameter.H:121
void setCallback(std::function< void(T const &)> cb)
Set the parameter's callback.
Definition: ParameterImpl.H:81
void set(T const &newVal)
Set the value of this Parameter.
Definition: ParameterImpl.H:89
virtual ~ParameterCore()
Destructor.
Definition: ParameterImpl.H:52
std::string category
Category of the parameter, as a string.
Definition: Parameter.H:108
std::string categorydescription
Category description.
Definition: Parameter.H:111
ParameterCore(ParameterDef< T > const &def)
Constructor.
Definition: ParameterImpl.H:46
virtual ~ParameterBase()
Destructor, will remove the parameter from its owner component.
Definition: ParameterImpl.H:30