Skip to content

Commit b5b13dc

Browse files
robert-burgerrobert-burger
committed
update: more docs
1 parent 94964d2 commit b5b13dc

3 files changed

Lines changed: 406 additions & 109 deletions

File tree

‎include/robotkernel/device_listener.h‎

Lines changed: 113 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,28 @@
2424
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2525
*/
2626

27+
/**
28+
* @file device_listener.h
29+
* @brief Abstract listener for device lifecycle events.
30+
*
31+
* Defines the interface for classes that want to be notified
32+
* about device additions and removals within the robotkernel
33+
* device registry.
34+
*
35+
* A listener registers interest in device events and receives:
36+
* - `notify_add_device()`
37+
* - `notify_remove_device()`
38+
*
39+
* When devices are added/removed, the runtime can call these
40+
* methods to let observers react (e.g., update UI, reconfigure
41+
* mappings, manage resource lifetimes).
42+
*
43+
* @note
44+
* - This class is abstract and must be implemented by concrete
45+
* listeners.
46+
* - Use shared pointers (`sp_device_listener_t`) to manage lifetime.
47+
*/
48+
2749
#ifndef ROBOTKERNEL_DEVICE_LISTENER_H
2850
#define ROBOTKERNEL_DEVICE_LISTENER_H
2951

@@ -34,31 +56,103 @@
3456

3557
namespace robotkernel {
3658

37-
class device_listener
59+
/**
60+
* @class device_listener
61+
* @brief Receiver of device lifecycle notifications.
62+
*
63+
* Listens for device registration and deregistration events.
64+
* Each listener has:
65+
* - an `owner`: logical owner of devices it cares about
66+
* - a `name`: human/product name for the listener itself
67+
*
68+
* Derived classes implement callbacks to respond to events.
69+
*/
70+
class device_listener
3871
{
39-
public:
40-
const std::string owner; //!< device owner
41-
const std::string name; //!< listener name
42-
43-
public:
44-
//! construction
45-
device_listener(const std::string& owner, const std::string& name) :
46-
owner(owner), name(name) {};
47-
48-
//! destruction
49-
virtual ~device_listener() = 0;
50-
51-
// add a named device
52-
virtual void notify_add_device(sp_device_t req) = 0;
53-
54-
// remove a named device
55-
virtual void notify_remove_device(sp_device_t req) = 0;
72+
public:
73+
/// Logical owner of devices this listener watches.
74+
const std::string owner;
75+
76+
/// Name of the listener (for logging/identification).
77+
const std::string name;
78+
79+
public:
80+
/**
81+
* @brief Constructor.
82+
*
83+
* @param owner
84+
* Logical owner or subsystem that this listener is
85+
* interested in.
86+
*
87+
* @param name
88+
* Identifier for this listener instance.
89+
*/
90+
device_listener(const std::string& owner,
91+
const std::string& name)
92+
: owner(owner),
93+
name(name)
94+
{
95+
}
96+
97+
/**
98+
* @brief Virtual destructor.
99+
*
100+
* Declared pure virtual to make this class abstract,
101+
* but defined inline to ensure proper deletion of derived
102+
* listener objects.
103+
*/
104+
virtual ~device_listener() = 0;
105+
106+
/**
107+
* @brief Called when a device is added.
108+
*
109+
* Derived classes implement this to react when a new
110+
* device gets registered (e.g., allocate resources,
111+
* update state).
112+
*
113+
* @param req
114+
* Shared pointer to the newly added device.
115+
*/
116+
virtual void notify_add_device(sp_device_t req) = 0;
117+
118+
/**
119+
* @brief Called when a device is removed.
120+
*
121+
* Derived listener can handle the removal (e.g.,
122+
* cleanup, reconfiguration, resource release).
123+
*
124+
* @param req
125+
* Shared pointer to the removed device.
126+
*/
127+
virtual void notify_remove_device(sp_device_t req) = 0;
56128
};
57129

58-
//! destruction
130+
// -----------------------------------------------------------------------------
131+
// Inline definitions
132+
// -----------------------------------------------------------------------------
133+
134+
/**
135+
* @brief Abstract base destructor definition.
136+
*
137+
* Although pure virtual, this is defined so that derived
138+
* destructors are called correctly when deleted via base
139+
* pointer.
140+
*/
59141
inline device_listener::~device_listener() {}
60142

143+
/**
144+
* @brief Shared pointer alias for device_listener.
145+
*/
61146
typedef std::shared_ptr<device_listener> sp_device_listener_t;
147+
148+
/**
149+
* @brief Map of listener name to listener pointer.
150+
*
151+
* Useful for managing registered listeners keyed by name.
152+
*
153+
* Key: listener identifier
154+
* Value: shared pointer to listener
155+
*/
62156
typedef std::map<std::pair<std::string, std::string>, sp_device_listener_t> device_listener_map_t;
63157

64158
}; // namespace robotkernel

‎include/robotkernel/log_base.h‎

Lines changed: 146 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,23 @@
2424
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
2525
*/
2626

27+
/**
28+
* @file log_base.h
29+
* @brief Base class for logging in robotkernel modules.
30+
*
31+
* Provides a common logging interface and log level configuration
32+
* support for modules, services, and other components within the
33+
* robotkernel framework.
34+
*
35+
* This class also implements the `svc_configure_loglevel` service
36+
* used to change log levels at runtime via service calls.
37+
*
38+
* Logging output is routed through the robotkernel logging facility.
39+
*
40+
* Derived classes should call `log()` with the appropriate level
41+
* to emit log messages.
42+
*/
43+
2744
#ifndef ROBOTKERNEL_LOG_BASE_H
2845
#define ROBOTKERNEL_LOG_BASE_H
2946

@@ -35,69 +52,145 @@
3552

3653
namespace robotkernel {
3754

55+
/**
56+
* @class log_base
57+
* @brief Base class implementing logging behavior for components.
58+
*
59+
* This class encapsulates:
60+
* - A configurable log level.
61+
* - A name and implementation identifier used in log output.
62+
* - Optional service to configure log levels at runtime.
63+
*
64+
* Components deriving from `log_base` gain a consistent logging
65+
* interface and integration with the robotkernel logging facility.
66+
*/
3867
class log_base :
3968
public services::robotkernel::log_base::svc_base_configure_loglevel
4069
{
4170
private:
42-
log_base(); //!< prevent default construction
43-
44-
public:
45-
loglevel ll; //!< loglevel loglevel
46-
std::string name; //!< name of module
47-
std::string impl; //!< name of implementation
48-
std::string service_prefix; //!< name of service
49-
50-
//! construction
51-
/*!
52-
* \param[in] ll Loglevel to set.
53-
*/
54-
log_base(loglevel ll);
55-
56-
//! construction
57-
/*!
58-
* \param node config node
59-
*/
60-
log_base(const std::string& name, const std::string& impl,
61-
const std::string& service_prefix, const YAML::Node& node = YAML::Node());
62-
63-
//! virtual destruction
64-
virtual ~log_base();
65-
66-
//! Return current loglevel
67-
const loglevel get_loglevel() const;
68-
69-
//! Set new loglevel
70-
/*!
71-
* \param[in] ll New loglevel to be set.
72-
*/
73-
void set_loglevel(loglevel ll);
74-
75-
//! svc_configure_loglevel
76-
/*!
77-
* \param[in] req Service request data.
78-
* \param[out] resp Service response data.
79-
*/
80-
void svc_configure_loglevel(
81-
const struct services::robotkernel::log_base::svc_req_configure_loglevel& req,
82-
struct services::robotkernel::log_base::svc_resp_configure_loglevel& resp) override;
83-
84-
//! log to kernel logging facility
85-
void log(robotkernel::loglevel lvl, const char *format, ...);
71+
/**
72+
* @brief Disabled default constructor.
73+
*
74+
* This class must be constructed with at least a log level
75+
* or with all identifying information present.
76+
*/
77+
log_base();
78+
79+
public:
80+
/// Current loglevel for this component.
81+
loglevel ll;
82+
83+
/// Component name used in log output.
84+
std::string name;
85+
86+
/// Implementation identifier (e.g. module/plugin type).
87+
std::string impl;
88+
89+
/// Optional prefix for service-related log entries.
90+
std::string service_prefix;
91+
92+
public:
93+
/**
94+
* @brief Construct a log_base with an explicit loglevel.
95+
*
96+
* @param[in] ll
97+
* Initial log level for this component.
98+
*/
99+
log_base(loglevel ll);
100+
101+
/**
102+
* @brief Construct a log_base with identifying information.
103+
*
104+
* @param[in] name
105+
* Human identifier for this instance (e.g., module name).
106+
*
107+
* @param[in] impl
108+
* Implementation name or type.
109+
*
110+
* @param[in] service_prefix
111+
* Optional prefix for log messages from services.
112+
*
113+
* @param[in] node
114+
* YAML configuration node (unused in base, available for derived use).
115+
*/
116+
log_base(const std::string& name,
117+
const std::string& impl,
118+
const std::string& service_prefix,
119+
const YAML::Node& node = YAML::Node());
120+
121+
/**
122+
* @brief Virtual destructor.
123+
*/
124+
virtual ~log_base();
125+
126+
/**
127+
* @brief Return the current log level.
128+
*
129+
* @return Current loglevel.
130+
*/
131+
const loglevel get_loglevel() const;
132+
133+
/**
134+
* @brief Set a new log level.
135+
*
136+
* Used internally and by the `svc_configure_loglevel` service
137+
* to adjust logging detail at runtime.
138+
*
139+
* @param[in] ll New log level value.
140+
*/
141+
void set_loglevel(loglevel ll);
142+
143+
/**
144+
* @brief Service callback for configuring loglevel.
145+
*
146+
* Implements the service logic for runtime log level configuration.
147+
* This override comes from the `svc_base_configure_loglevel` interface.
148+
*
149+
* @param[in] req Service request containing a log level.
150+
* @param[out] resp Service response.
151+
*/
152+
void svc_configure_loglevel(
153+
const struct services::robotkernel::log_base::svc_req_configure_loglevel& req,
154+
struct services::robotkernel::log_base::svc_resp_configure_loglevel& resp) override;
155+
156+
/**
157+
* @brief Emit a log message to the robotkernel logging facility.
158+
*
159+
* @param[in] lvl
160+
* Log level to use for this message.
161+
*
162+
* @param[in] format
163+
* printf-style format string.
164+
*
165+
* @param[in] …
166+
* Arguments passed to the format string.
167+
*/
168+
void log(robotkernel::loglevel lvl, const char *format, ...);
86169
};
87170

88-
//! Return current loglevel
89-
inline const loglevel log_base::get_loglevel() const {
90-
return ll;
91-
}
171+
// -----------------------------------------------------------------------------
172+
// Inline member implementations
173+
// -----------------------------------------------------------------------------
92174

93-
//! Set new loglevel
94-
/*!
95-
* \param[in] ll New loglevel to be set.
175+
/**
176+
* @brief Return the stored log level.
177+
*
178+
* @return The current loglevel.
96179
*/
97-
inline void log_base::set_loglevel(loglevel ll) {
98-
this->ll = ll;
180+
inline const loglevel log_base::get_loglevel() const
181+
{
182+
return ll;
99183
}
100184

185+
/**
186+
* @brief Set the stored loglevel.
187+
*
188+
* @param[in] ll The new loglevel.
189+
*/
190+
inline void log_base::set_loglevel(loglevel ll)
191+
{
192+
this->ll = ll;
193+
}
101194

102195
}; // namespace robotkernel
103196

0 commit comments

Comments
 (0)