JeVois  1.5
JeVois Smart Embedded Machine Vision Toolkit
Share this page:
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  std::string strval; jevois::paramValToString(newVal, strval);
98  os << descriptor() << ": Provided value [" << strval << "] rejected because Parameter is frozen";
99  throw std::range_error(os.str());
100  }
101 
102 
103  // Is the value authorized, depending on the type of valid values we have:
104  if (itsDef.itsValidValuesSpec->checkValueValidity(newVal) == false)
105  {
106  std::ostringstream os;
107  std::string strval; jevois::paramValToString(newVal, strval);
108  os << descriptor() << ": Provided value [" << strval << "] not valid according to specification "
109  << itsDef.itsValidValuesSpec->str();
110  throw std::range_error(os.str());
111  }
112 
113  // If we have a callback, see whether it likes this change:
114  if (itsCallback)
115  {
116  try { itsCallback(newVal); }
117  catch (std::exception const & e)
118  {
119  std::ostringstream os;
120  std::string strval; jevois::paramValToString(newVal, strval);
121  os << descriptor() << ": Provided value [" << strval << "] rejected by callback with reason [" << e.what() << ']';
122  throw std::range_error(os.str());
123  }
124  catch (...)
125  {
126  std::ostringstream os;
127  std::string strval; jevois::paramValToString(newVal, strval);
128  os << descriptor() << ": Provided value [" << strval << "] rejected by callback with unknown reason";
129  throw std::range_error(os.str());
130  }
131 
132  // We have been set at least once now:
133  itsVirgin = false;
134  }
135 
136  // If we made it through, all is ok. Change the value:
137  {
138  boost::upgrade_to_unique_lock<boost::shared_mutex> ulock(lck);
139  itsVal = newVal;
140  }
141 }
142 
143 // ######################################################################
144 template <typename T> inline
145 void jevois::ParameterCore<T>::strset(std::string const & valstring)
146 { jevois::ParameterCore<T>::set(jevois::detail::paramValFromString<T>(valstring, this)); }
147 
148 // ######################################################################
149 template <typename T> inline
150 std::string const jevois::ParameterCore<T>::strget() const
152 
153 // ######################################################################
154 template <typename T> inline
156 {
157  boost::unique_lock<boost::shared_mutex> ulck(itsMutex);
158  itsVal = def.defaultValue();
159  *(const_cast<jevois::ParameterDef<T> *>(& itsDef)) = def;
160 }
161 
162 // ######################################################################
163 template <typename T> inline
165 {
166  boost::shared_lock<boost::shared_mutex> _(itsMutex);
167 
168  // If we have a callback, call it with our current value:
169  if (itsCallback && itsVirgin)
170  {
171  try { itsCallback(itsVal); }
172  catch (std::exception const & e)
173  {
174  std::ostringstream os;
175  std::string strval; jevois::paramValToString(itsVal, strval);
176  os << descriptor() << ": Value [" << strval << "] rejected by callback with reason [" << e.what() << ']';
177  throw std::range_error(os.str());
178  }
179  catch (...)
180  {
181  std::ostringstream os;
182  std::string strval; jevois::paramValToString(itsVal, strval);
183  os << descriptor() << ": Value [" << strval << "] rejected by callback with unknown reason";
184  throw std::range_error(os.str());
185  }
186  }
187 }
188 
189 // ######################################################################
190 template <typename T> inline
192 {
194 
195  boost::shared_lock<boost::shared_mutex> lck(itsMutex);
196 
197  ps.descriptor = descriptor();
198  ps.name = itsDef.name();
199  ps.description = itsDef.description();
200  ps.valuetype = jevois::demangledName<T>();
201  ps.defaultvalue = itsDef.defaultValueString();
202  ps.value = strget();
203  ps.validvalues = itsDef.validValuesString();
204  ps.category = itsDef.category().name;
205  ps.categorydescription = itsDef.category().description;
206  ps.frozen = itsFrozen;
207 
208  return ps;
209 }
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&#39;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.
virtual std::string const & name() const override
Get the parameter name.
Definition: ParameterImpl.H:60
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
A Parameter Definition.
Definition: ParameterDef.H:88
bool itsVirgin
Param has not yet been explicitly set, need to call the callback (if any) at init time...
Definition: Parameter.H:156
T get() const
Get the value of this Parameter.
Definition: ParameterImpl.H:73
void paramValToString(T const &val, std::string &result)
Machine-readable conversion of T to a string, for use in jevois::Parameter.
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.
virtual Component const * owner() const =0
Get the Component to which this Parameter is attached, or nullptr (individual parameters must overrid...
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
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
std::string descriptor() const
Get our full descriptor (including all parents) as [Instancename]:[...]:[...].
Definition: Component.C:264
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&#39;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
boost::shared_mutex itsMutex
Mutex to protect the parameter value.
Definition: Parameter.H:154
std::string categorydescription
Category description.
Definition: Parameter.H:111
volatile bool itsFrozen
When true, parameter is frozen (read-only, does not show up in help message)
Definition: Parameter.H:155
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