Add lttng::locked_reference

A locked reference is a wrapper that allows functions to return a
protected/synchronized version of an object. My immediate use-case for
this helper is making it easier to call functions that return an
rcu-protected object (require the caller to hold the RCU reader lock for
the duration of its use of that object) in an exception safe manner.

As such, these functions can now return
lttng::locked_reference<MyType, lttng::urcu::unique_read_lock> which
ensures the RCU reader lock is held for as long as the object is used.

Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
Change-Id: I9f4b7f918ba01491d3de14a1a570c83586f407ae

diff --git a/src/common/Makefile.am b/src/common/Makefile.am
index 23d33e983b19bb3288c9edd565e29c6d2c9a4e31..66ab77d05d9cf825c61feb7c8edb49d77f85a6e1 100644 (file)
--- a/src/common/Makefile.am
+++ b/src/common/Makefile.am
@@ -88,6 +88,7 @@ libcommon_lgpl_la_SOURCES = \
        format.hpp \
        kernel-probe.cpp \
        location.cpp \
+       locked-reference.hpp \
        log-level-rule.cpp \
        make-unique.hpp \
        make-unique-wrapper.hpp \

diff --git a/src/common/locked-reference.hpp b/src/common/locked-reference.hpp
new file mode 100644 (file)
index 0000000..e0ff3f2
--- /dev/null
+++ b/src/common/locked-reference.hpp
@@ -0,0 +1,61 @@
+/*
+ * Copyright (C) 2022 Jérémie Galarneau <jeremie.galarneau@efficios.com>
+ *
+ * SPDX-License-Identifier: LGPL-2.1-only
+ *
+ */
+
+#ifndef LTTNG_LOCKED_REFERENCE_H
+#define LTTNG_LOCKED_REFERENCE_H
+
+#define _LGPL_SOURCE
+#include <mutex>
+
+namespace lttng {
+
+/*
+ * A locked reference is useful to return a reference to an object
+ * while ensuring that the caller uses it within a given locking context.
+ *
+ * For instance, a number of look-up APIs return an object and require the
+ * caller to hold the RCU reader lock for the duration of their use of the
+ * return value.
+ *
+ * Using a locked_reference, a function returning such an object can:
+ *   - acquire the rcu read lock using a unique_read_lock,
+ *   - perform its look-up
+ *   - return a reference to which the unique_read_lock is transferred.
+ *
+ * Note that this locked reference can be used like a pointer
+ * (see operators `*` and `->`). However, note that it is a _reference_.
+ * Hence, _it can't be null_.
+ *
+ * Functions returning this type will most likely throw an exception
+ * when the look-up fails.
+ */
+template <class WrappedType, class UniqueLockType>
+class locked_reference {
+public:
+       locked_reference(WrappedType& value, UniqueLockType&& lock) :
+               _value(value), _lock(std::move(lock))
+       {
+       }
+
+       WrappedType& operator*() const
+       {
+               return _value;
+       }
+
+        WrappedType* operator->() const
+       {
+               return &_value;
+       }
+
+private:
+       WrappedType& _value;
+       UniqueLockType _lock;
+};
+
+} /* namespace lttng */
+
+#endif /* LTTNG_LOCKED_REFERENCE_H */