summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorBrian Gianforcaro <bgianf@serenityos.org>2021-09-27 18:29:23 -0700
committerAndreas Kling <kling@serenityos.org>2021-09-28 10:57:00 +0200
commitafb09e84db0ae1a6933a193a8824f3a46dbacdab (patch)
tree3f08ac2f37e5f955cd0df25bf6ff278023be1e99 /Documentation
parentf71f1d66d6545fff6c10b1e30648901bf1c4b795 (diff)
downloadserenity-afb09e84db0ae1a6933a193a8824f3a46dbacdab.zip
Documentation: Add `AK::SourceLocation` pattern to Patterns.md
Document the emergent pattern of using `SourceLocation` for capture file, line, function name information when calling an API.
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/Patterns.md57
1 files changed, 57 insertions, 0 deletions
diff --git a/Documentation/Patterns.md b/Documentation/Patterns.md
index 425d7c6324..6ef45fc822 100644
--- a/Documentation/Patterns.md
+++ b/Documentation/Patterns.md
@@ -112,3 +112,60 @@ TEST_CASE(string_view_literal_operator)
EXPECT_EQ(literal_view, test_string);
}
```
+
+## Source Location
+
+C++20 added std::source_location, which lets you capture the
+callers __FILE__ / __LINE__ / __FUNCTION__ etc as a default
+argument to functions.
+See: https://en.cppreference.com/w/cpp/utility/source_location
+
+`AK::SourceLocation` is the implementation of this feature in
+SerenityOS. It's become the idiomatic way to capture the location
+when adding extra debugging instrumentation, without resorting to
+litering the code with preprocessor macros.
+
+To use it, you can add the `AK::SourceLocation` as a default argument
+to any function, using `AK::SourceLocatin::current()` to initialize the
+default argument.
+
+Example Usage:
+```cpp
+#include <AK/SourceLocation.h>
+#include <AK/StringView.h>
+
+static StringView example_fn(const SourceLocation& loc = SourceLocation::current())
+{
+ return loc.function_name();
+}
+
+int main(int, char**)
+{
+ return example_fn().length();
+}
+```
+
+If you only want to only capture `AK::SourceLocation` data with a certain debug macro enabled, avoid
+adding `#ifdef`'s to all functions which have the `AK::SourceLocation` argument. Since SourceLocation
+is just a simple struct, you can just declare an empty class which can be optimized away by the
+compiler, and alias both to the same name.
+
+Example Usage:
+
+```cpp
+
+#if LOCK_DEBUG
+# include <AK/SourceLocation.h>
+#endif
+
+#if LOCK_DEBUG
+using LockLocation = SourceLocation;
+#else
+struct LockLocation {
+ static constexpr LockLocation current() { return {}; }
+
+private:
+ constexpr LockLocation() = default;
+};
+#endif
+```