From ab8ef5750d902aa0dfa9724aed908a1143bb5a00 Mon Sep 17 00:00:00 2001 From: Norman Feske Date: Wed, 20 May 2020 16:40:17 +0200 Subject: [PATCH] doc: tweaks for updated Genode Foundations book --- repos/base/include/base/blockade.h | 14 +++++++++-- repos/base/include/base/log.h | 10 ++++---- repos/base/include/base/mutex.h | 26 +++++++++++++++++++-- repos/base/include/base/thread.h | 3 +++ repos/base/include/cpu_thread/cpu_thread.h | 3 +++ repos/base/include/util/xml_node.h | 7 ++++++ repos/os/include/block_session/connection.h | 14 +++++++++++ 7 files changed, 68 insertions(+), 9 deletions(-) diff --git a/repos/base/include/base/blockade.h b/repos/base/include/base/blockade.h index 03557f459..20723549c 100644 --- a/repos/base/include/base/blockade.h +++ b/repos/base/include/base/blockade.h @@ -1,7 +1,15 @@ /* - * \brief Blockade primitives + * \brief Blockade primitive * \author Alexander Boettcher * \date 2020-01-24 + * + * A 'Blockade' is a locking primitive designated for deliberately pausing + * the execution of a thread until woken up by another thread. It is typically + * used as a mechanism for synchonizing the startup of threads. + * + * At initialization time, a blockade is in locked state. A thread can pause + * its own execution by calling the 'block()' method. Another thread can wake + * up the paused thread by calling 'wakeup()' on the blockade. */ /* @@ -23,10 +31,12 @@ namespace Genode { class Blockade; } class Genode::Blockade : Noncopyable { private: + Lock _lock; public: - explicit Blockade() : _lock(Lock::LOCKED) { } + + Blockade() : _lock(Lock::LOCKED) { } void block() { _lock.lock(); } diff --git a/repos/base/include/base/log.h b/repos/base/include/base/log.h index 320edc819..2a17dfacf 100644 --- a/repos/base/include/base/log.h +++ b/repos/base/include/base/log.h @@ -174,11 +174,11 @@ namespace Genode { void raw(ARGS &&... args) { Raw::output(args...); } - /** - * Write 'args' to the trace buffer if tracing is enabled - * - * The message is prefixed with a timestamp value - */ + /** + * Write 'args' to the trace buffer if tracing is enabled + * + * The message is prefixed with a timestamp value + */ template void trace(ARGS && ... args) { Trace_output::trace_output().output(Trace::timestamp(), ": ", args...); } diff --git a/repos/base/include/base/mutex.h b/repos/base/include/base/mutex.h index 40cc87d45..e1f89d11b 100644 --- a/repos/base/include/base/mutex.h +++ b/repos/base/include/base/mutex.h @@ -1,7 +1,25 @@ /* - * \brief Mutex primitives + * \brief Mutex primitive * \author Alexander Boettcher * \date 2020-01-24 + * + * A 'Mutex' is a locking primitive designated for the mutual exclusion of + * multiple threads executing a critical section, which is typically code that + * mutates a shared variable. + * + * At initialization time, a mutex is in unlocked state. To enter and leave a + * critical section, the methods 'acquire()' and 'release()' are provided. + * + * A mutex must not be used recursively. The subsequential attempt of aquiring + * a mutex twice by the same thread ultimately results in a deadlock. This + * misbehavior generates a warning message at runtime. + * + * Only the thread that aquired the mutex is permitted to release the mutex. + * The violation of this invariant generates a warning message and leaves the + * mutex unchanged. + * + * A 'Mutex::Guard' is provided, which acquires a mutex at construction time + * and releases it automatically at the destruction time of the guard. */ /* @@ -23,10 +41,12 @@ namespace Genode { class Mutex; } class Genode::Mutex : Noncopyable { private: + Lock _lock { }; public: - explicit Mutex() { } + + Mutex() { } void acquire(); void release(); @@ -34,9 +54,11 @@ class Genode::Mutex : Noncopyable class Guard { private: + Mutex &_mutex; public: + explicit Guard(Mutex &mutex) : _mutex(mutex) { _mutex.acquire(); } ~Guard() { _mutex.release(); } diff --git a/repos/base/include/base/thread.h b/repos/base/include/base/thread.h index 3e3331ffa..67e11baef 100644 --- a/repos/base/include/base/thread.h +++ b/repos/base/include/base/thread.h @@ -332,6 +332,9 @@ class Genode::Thread /** * Cancel currently blocking operation + * + * \deprecated + * \noapi */ void cancel_blocking(); diff --git a/repos/base/include/cpu_thread/cpu_thread.h b/repos/base/include/cpu_thread/cpu_thread.h index e0c23fd7b..43c6a2e9f 100644 --- a/repos/base/include/cpu_thread/cpu_thread.h +++ b/repos/base/include/cpu_thread/cpu_thread.h @@ -57,6 +57,9 @@ struct Genode::Cpu_thread : Interface /** * Cancel a currently blocking operation + * + * \deprecated + * \noapi */ virtual void cancel_blocking() = 0; diff --git a/repos/base/include/util/xml_node.h b/repos/base/include/util/xml_node.h index fdd62a5b5..b070b3d28 100644 --- a/repos/base/include/util/xml_node.h +++ b/repos/base/include/util/xml_node.h @@ -1123,6 +1123,13 @@ class Genode::Xml_node }; +/** + * Utility for unquoting XML attributes + * + * The 'Xml_unquoted' utility can be used to revert quoted XML attribute + * values. Such quoting is needed whenever an attribute value can contain '"' + * characters. + */ class Genode::Xml_unquoted : Noncopyable { private: diff --git a/repos/os/include/block_session/connection.h b/repos/os/include/block_session/connection.h index b888e9ae7..cfafe8d9c 100644 --- a/repos/os/include/block_session/connection.h +++ b/repos/os/include/block_session/connection.h @@ -2,6 +2,20 @@ * \brief Connection to block service * \author Norman Feske * \date 2019-04-10 + * + * The 'Block::Connection' is equipped with an interface for the implementation + * of robust block-session clients that perform block I/O in an asynchronous + * fashion. + * + * An application-defined JOB type, inherited from 'Connection::Job', + * encapsulates the application's context information associated with a block + * operation. + * + * The life cycle of the jobs is implemented by the 'Connection' and driven by + * the application's invocation of 'Connection::update_jobs'. The 'update_jobs' + * mechanism takes three hook functions as arguments, which implement the + * applications-defined policy for producing and consuming data, and for the + * completion of jobs. */ /*