From 405a9d214412e4cc63d3321b4cc8d92edd16b691 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Wed, 22 May 2019 15:37:45 +0200 Subject: [PATCH] Refinements for updated "Genode Foundations" book - Improve API descriptions - Remove obsolete Xml_node::value method (fixes #3323) - Follow coding style 'const char' -> 'char const' - Avoid '>>' when nesting templates (limitation of parse_cxx) --- repos/base/include/base/allocator_avl.h | 2 +- repos/base/include/base/entrypoint.h | 10 ++-- .../include/io_mem_session/io_mem_session.h | 2 +- repos/base/include/parent/parent.h | 4 +- repos/base/include/util/fifo.h | 36 +++++++------- repos/base/include/util/xml_node.h | 47 ++++++++++--------- repos/os/include/block_session/connection.h | 2 +- 7 files changed, 53 insertions(+), 50 deletions(-) diff --git a/repos/base/include/base/allocator_avl.h b/repos/base/include/base/allocator_avl.h index 41cf9df80..9e24e6712 100644 --- a/repos/base/include/base/allocator_avl.h +++ b/repos/base/include/base/allocator_avl.h @@ -210,7 +210,7 @@ class Genode::Allocator_avl_base : public Range_allocator /** * Clean up the allocator and detect dangling allocations * - * This function is called at the destruction time of the allocator. It + * This method is called at the destruction time of the allocator. It * makes sure that the allocator instance releases all memory obtained * from the meta-data allocator. */ diff --git a/repos/base/include/base/entrypoint.h b/repos/base/include/base/entrypoint.h index b329c30da..046bb50ae 100644 --- a/repos/base/include/base/entrypoint.h +++ b/repos/base/include/base/entrypoint.h @@ -91,11 +91,11 @@ class Genode::Entrypoint : Noncopyable Reconstructible _sig_rec { }; - Lock _deferred_signals_mutex { }; - List> _deferred_signals { }; + Lock _deferred_signals_mutex { }; + List > _deferred_signals { }; void _handle_deferred_signals() { } - Constructible> _deferred_signal_handler { }; + Constructible > _deferred_signal_handler { }; bool _suspended = false; void (*_suspended_callback) () = nullptr; @@ -124,7 +124,7 @@ class Genode::Entrypoint : Noncopyable * resume mechanism. */ void _handle_suspend() { _suspended = true; } - Constructible> _suspend_dispatcher { }; + Constructible > _suspend_dispatcher { }; void _dispatch_signal(Signal &sig); void _defer_signal(Signal &sig); @@ -136,7 +136,7 @@ class Genode::Entrypoint : Noncopyable bool _stop_signal_proxy { false }; void _handle_stop_signal_proxy() { _stop_signal_proxy = true; } - Constructible> _stop_signal_proxy_handler { }; + Constructible > _stop_signal_proxy_handler { }; friend class Startup; diff --git a/repos/base/include/io_mem_session/io_mem_session.h b/repos/base/include/io_mem_session/io_mem_session.h index 103184874..a607578c6 100644 --- a/repos/base/include/io_mem_session/io_mem_session.h +++ b/repos/base/include/io_mem_session/io_mem_session.h @@ -1,5 +1,5 @@ /* - * \brief I/O-memory session interface + * \brief Memory-mapped I/O session interface * \author Christian Helmuth * \date 2006-08-01 */ diff --git a/repos/base/include/parent/parent.h b/repos/base/include/parent/parent.h index b4141d8a1..92cfd86c0 100644 --- a/repos/base/include/parent/parent.h +++ b/repos/base/include/parent/parent.h @@ -101,12 +101,12 @@ class Genode::Parent /** * Emulation of the original synchronous root interface * - * This function transparently spawns a proxy "root" entrypoint that + * This method transparently spawns a proxy "root" entrypoint that * dispatches asynchronous session-management operations (as issued * by the parent) to the local root interfaces via component-local * RPC calls. * - * The function solely exists for API compatibility. + * The method solely exists for API compatibility. */ static void announce(Service_name const &service_name, Root_capability service_root); diff --git a/repos/base/include/util/fifo.h b/repos/base/include/util/fifo.h index b3a3e1286..a9d861f43 100644 --- a/repos/base/include/util/fifo.h +++ b/repos/base/include/util/fifo.h @@ -22,7 +22,7 @@ namespace Genode { /** - * Fifo queue + * First-in first-out (FIFO) queue * * \param QT queue element type */ @@ -75,16 +75,13 @@ class Genode::Fifo Fifo() { } /** - * If queue is not empty then call - * lambda 'func' of type 'void (QT&)' - * with the head element + * Call 'func' of type 'void (QT&)' the head element */ template - void head(FUNC const &func) const { - if (_head) func(*_head); } + void head(FUNC const &func) const { if (_head) func(*_head); } /** - * Remove element explicitely from queue + * Remove element explicitly from queue */ void remove(QT &qe) { @@ -93,9 +90,10 @@ class Genode::Fifo /* if specified element is the first of the queue */ if (&qe == _head) { _head = qe.Fifo::Element::_next; - if (!_head) _tail = nullptr; - } - else { + if (!_head) + _tail = nullptr; + + } else { /* search specified element in the queue */ Element *e = _head; @@ -131,10 +129,8 @@ class Genode::Fifo _tail = &e; } - /** - * Call lambda 'func' of type 'void (QT&)' - * for each queue element in order + * Call 'func' of type 'void (QT&)' for each element in order */ template void for_each(FUNC const &func) const @@ -149,8 +145,7 @@ class Genode::Fifo } /** - * If queue is not empty then remove head and - * call lambda 'func' of type 'void (QT&)' + * Remove head and call 'func' of type 'void (QT&)' */ template void dequeue(FUNC const &func) @@ -175,8 +170,11 @@ class Genode::Fifo } /** - * If queue is not empty then remove elements in order and - * call lambda 'func' of type 'void (QT&)' + * Remove all fifo elements + * + * This method removes all elements in order and calls the lambda + * 'func' of type 'void (QT&)' for each element. It is intended to be + * used prior the destruction of the FIFO. */ template void dequeue_all(FUNC const &func) @@ -191,9 +189,9 @@ class Genode::Fifo * * \param T type of compound object to be organized in a FIFO * - * This helper allow the creation of FIFOs that use member variables to + * This helper allows the creation of FIFOs that use member variables to * connect their elements. This way, the organized type does not need to - * publicly inherit 'Fifo::Element'. Furthermore objects can easily + * publicly inherit 'Fifo::Element'. Furthermore, objects can easily * be organized in multiple FIFOs by embedding multiple 'Fifo_element' * member variables. */ diff --git a/repos/base/include/util/xml_node.h b/repos/base/include/util/xml_node.h index 518c607d3..c4ca51e90 100644 --- a/repos/base/include/util/xml_node.h +++ b/repos/base/include/util/xml_node.h @@ -92,6 +92,9 @@ class Genode::Xml_attribute /** * Return attribute type as null-terminated string + * + * \deprecated + * \noapi */ void type(char *dst, size_t max_len) const { @@ -110,7 +113,7 @@ class Genode::Xml_attribute /** * Return true if attribute has specified type */ - bool has_type(const char *type) { + bool has_type(char const *type) { return strlen(type) == _name.len() && strcmp(type, _name.start(), _name.len()) == 0; } @@ -118,6 +121,7 @@ class Genode::Xml_attribute * Return size of value * * \deprecated use 'with_raw_node' instead + * \noapi */ char const *value_base() const { return _value.start() + 1; } @@ -139,7 +143,7 @@ class Genode::Xml_attribute /** * Return true if attribute has the specified value */ - bool has_value(const char *value) const { + bool has_value(char const *value) const { return strlen(value) == (_value.len() - 2) && !strcmp(value, _value.start() + 1, _value.len() - 2); } @@ -165,6 +169,7 @@ class Genode::Xml_attribute * Return attribute value as null-terminated string * * \deprecated + * \noapi */ void value(char *dst, size_t max_len) const { @@ -205,6 +210,7 @@ class Genode::Xml_attribute * Return attribute value as 'Genode::String' * * \deprecated use 'value(String &out' instead + * \noapi */ template void value(String *out) const @@ -217,6 +223,7 @@ class Genode::Xml_attribute * Return attribute value as typed value * * \deprecated use 'value(T &out)' instead + * \noapi */ template bool value(T *out) const @@ -500,7 +507,7 @@ class Genode::Xml_node int _num_sub_nodes { 0 }; /* number of immediate sub nodes */ - const char * _addr; /* first character of XML data */ + char const * _addr; /* first character of XML data */ size_t _max_len; /* length of XML data in characters */ Tag _start_tag; Tag _end_tag; @@ -560,9 +567,9 @@ class Genode::Xml_node } /* reaching the same depth as the start tag */ - const char *start_name = start_tag.name().start(); + char const *start_name = start_tag.name().start(); size_t start_len = start_tag.name().len(); - const char *curr_name = curr_tag.name().start(); + char const *curr_name = curr_tag.name().start(); size_t curr_len = curr_tag.name().len(); /* on mismatch of start tag and end tag, return invalid tag */ @@ -610,7 +617,7 @@ class Genode::Xml_node * \throw Nonexistent_sub_node * \throw Invalid_syntax */ - Xml_node _sub_node(const char *at) const + Xml_node _sub_node(char const *at) const { if (at < _addr || (size_t)(at - _addr) >= _max_len) throw Nonexistent_sub_node(); @@ -633,7 +640,7 @@ class Genode::Xml_node * * \throw Invalid_syntax */ - Xml_node(const char *addr, size_t max_len = ~0UL) + Xml_node(char const *addr, size_t max_len = ~0UL) : _addr(addr), _max_len(max_len), @@ -649,6 +656,8 @@ class Genode::Xml_node /** * Request type name of XML node as null-terminated string + * + * \noapi */ void type_name(char *dst, size_t max_len) const { _start_tag.name().string(dst, max_len); } @@ -662,6 +671,7 @@ class Genode::Xml_node * Return pointer to start of node * * \deprecated use 'with_raw_node' instead + * \noapi */ char const *addr() const { return _addr; } @@ -689,7 +699,7 @@ class Genode::Xml_node /** * Return true if tag is of specified type */ - bool has_type(const char *type) const { + bool has_type(char const *type) const { return (!strcmp(type, _start_tag.name().start(), _start_tag.name().len()) && strlen(type) == _start_tag.name().len()); } @@ -738,13 +748,6 @@ class Genode::Xml_node */ char const *content_base() const { return content_addr(); } - /** - * Return content as out value - * - * \deprecated use with_raw_content instead - */ - template bool value(T *out) const { return value(*out); } - /** * Export decoded node content from XML node * @@ -794,7 +797,7 @@ class Genode::Xml_node /** * Return XML node following the current one * - * \throw Nonexistent_sub_node sub sequent node does not exist + * \throw Nonexistent_sub_node subsequent node does not exist */ Xml_node next() const { @@ -808,8 +811,10 @@ class Genode::Xml_node * Return next XML node of specified type * * \param type type of XML node, or nullptr for matching any type + * + * \throw Nonexistent_sub_node subsequent node does not exist */ - Xml_node next(const char *type) const + Xml_node next(char const *type) const { Xml_node node = next(); for (; type && !node.has_type(type); node = node.next()); @@ -819,7 +824,7 @@ class Genode::Xml_node /** * Return true if node is the last of a node sequence */ - bool last(const char *type = 0) const + bool last(char const *type = 0) const { try { next(type); return false; } catch (Nonexistent_sub_node) { return true; } @@ -851,9 +856,9 @@ class Genode::Xml_node /** * Return first sub node that matches the specified type * - * \throw Nonexistent_sub_node no such sub_node exists + * \throw Nonexistent_sub_node no such sub node exists */ - Xml_node sub_node(const char *type) const + Xml_node sub_node(char const *type) const { if (_num_sub_nodes > 0) { @@ -940,7 +945,7 @@ class Genode::Xml_node * \throw Nonexistent_attribute no such attribute exists * \return XML attribute */ - Xml_attribute attribute(const char *type) const + Xml_attribute attribute(char const *type) const { /* iterate, beginning with the first attribute of the node */ for (Xml_attribute a = _start_tag.attribute(); ; a = a.next()) diff --git a/repos/os/include/block_session/connection.h b/repos/os/include/block_session/connection.h index a5bdd6a71..b888e9ae7 100644 --- a/repos/os/include/block_session/connection.h +++ b/repos/os/include/block_session/connection.h @@ -189,7 +189,7 @@ struct Block::Connection : Genode::Connection, Session_client /** * Jobs that are pending for submission */ - Genode::Fifo> _pending { }; + Genode::Fifo > _pending { }; /** * Process a single acknowledgement