Merge pull request #9792 from poettering/hashmap-mempool

minor hashmap fixes

27 files changed, 93 insertions, 129 deletions

diff --git a/man/libudev.xml b/man/libudev.xml
index 8cb4ba59f..382c1aa25 100644
--- a/man/libudev.xml
+++ b/man/libudev.xml
@@ -48,11 +48,9 @@
     <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
     It is used to track library state and link objects together. No
     global state is used by libudev, everything is always linked to
-    a udev context. Furthermore, multiple different udev contexts can
-    be used in parallel by multiple threads. However, a single context
-    must not be accessed by multiple threads in parallel. The caller
-    is responsible for providing suitable locking if they intend to use
-    it from multiple threads.</para>
+    a udev context.</para>
+
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <para>To introspect a local device on a system, a udev device
     object can be created via
diff --git a/man/sd-bus-errors.xml b/man/sd-bus-errors.xml
index 50abf4c07..c89651154 100644
--- a/man/sd-bus-errors.xml
+++ b/man/sd-bus-errors.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd-bus-errors">
+<refentry id="sd-bus-errors"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd-bus-errors</title>
@@ -259,15 +260,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para>The various error definitions described here are available
-    as a shared library, which can be compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd-journal.xml b/man/sd-journal.xml
index 8bfcb90ca..3fa6c75b7 100644
--- a/man/sd-journal.xml
+++ b/man/sd-journal.xml
@@ -77,16 +77,15 @@
   <refsect1>
     <title>Thread safety</title>
 
-    <para>Functions that operate on the <structname>sd_journal</structname> object are thread
-    agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at
-    a time, but multiple threads may use multiple such objects safely. Other functions —
-    those that are used to send entries to the journal, like
-    <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    and similar, or those that are used to retrieve global information like
-    <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    and
+    <para>Functions that operate on <structname>sd_journal</structname> objects are thread agnostic — given
+    <structname>sd_journal</structname> pointer may only be used from one specific thread at all times (and it has to
+    be the very same one during the entire lifetime of the object), but multiple, independent threads may use multiple,
+    independent objects safely. Other functions — those that are used to send entries to the journal, like
+    <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar,
+    or those that are used to retrieve global information like
+    <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
     <citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>
-    — are thread-safe and may be called from multiple threads in parallel.</para>
+    — are fully thread-safe and may be called from multiple threads in parallel.</para>
   </refsect1>
 
   <xi:include href="libsystemd-pkgconfig.xml" />
diff --git a/man/sd_bus_add_match.xml b/man/sd_bus_add_match.xml
index a22d443ce..c4f24aed3 100644
--- a/man/sd_bus_add_match.xml
+++ b/man/sd_bus_add_match.xml
@@ -8,7 +8,7 @@
   Copyright © 2016 Julian Orth
 -->
 
-<refentry id="sd_bus_add_match">
+<refentry id="sd_bus_add_match" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_add_match</title>
@@ -154,9 +154,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para><function>sd_bus_add_match()</function> and the other functions described here are available as a shared
-    library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml
index 107291f26..dbe05a189 100644
--- a/man/sd_bus_error_add_map.xml
+++ b/man/sd_bus_error_add_map.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_error_add_map">
+<refentry id="sd_bus_error_add_map"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_error_add_map</title>
@@ -123,15 +124,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para>The various error definitions described here are available
-    as a shared library, which can be compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_is_open.xml b/man/sd_bus_is_open.xml
index 5cd2d18c4..0388db82a 100644
--- a/man/sd_bus_is_open.xml
+++ b/man/sd_bus_is_open.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_is_open">
+<refentry id="sd_bus_is_open"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_is_open</title>
@@ -88,13 +89,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_is_open()</function> and <function>sd_bus_is_ready()</function> are available as
-    a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_path_encode.xml b/man/sd_bus_path_encode.xml
index 4c60a8fa3..03130a697 100644
--- a/man/sd_bus_path_encode.xml
+++ b/man/sd_bus_path_encode.xml
@@ -6,7 +6,7 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_path_encode">
+<refentry id="sd_bus_path_encode" xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_path_encode</title>
@@ -141,15 +141,7 @@
     by the caller.</para>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_path_encode()</function> and
-    <function>sd_bus_path_decode()</function> are available as a
-    shared library, which can be compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_request_name.xml b/man/sd_bus_request_name.xml
index 54a14c877..3c98b60c6 100644
--- a/man/sd_bus_request_name.xml
+++ b/man/sd_bus_request_name.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_request_name">
+<refentry id="sd_bus_request_name"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_request_name</title>
@@ -193,13 +194,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para>The <function>sd_bus_acquire_name()</function> and the other interfaces described here are available as a
-    shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_set_connected_signal.xml b/man/sd_bus_set_connected_signal.xml
index 9dd47bc4d..32fc630cf 100644
--- a/man/sd_bus_set_connected_signal.xml
+++ b/man/sd_bus_set_connected_signal.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_set_connected_signal">
+<refentry id="sd_bus_set_connected_signal"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_set_connected_signal</title>
@@ -94,13 +95,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_set_connected_signal()</function> and <function>sd_bus_get_connected_signal()</function> are available as
-    a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_set_sender.xml b/man/sd_bus_set_sender.xml
index 512fffcf0..556e72cef 100644
--- a/man/sd_bus_set_sender.xml
+++ b/man/sd_bus_set_sender.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_set_sender">
+<refentry id="sd_bus_set_sender"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_set_sender</title>
@@ -89,13 +90,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_set_sender()</function> and <function>sd_bus_get_sender()</function> are available as
-    a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_bus_set_watch_bind.xml b/man/sd_bus_set_watch_bind.xml
index 41a4bc27d..129b98c5f 100644
--- a/man/sd_bus_set_watch_bind.xml
+++ b/man/sd_bus_set_watch_bind.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_bus_set_watch_bind">
+<refentry id="sd_bus_set_watch_bind"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_bus_set_watch_bind</title>
@@ -100,13 +101,7 @@
     </variablelist>
   </refsect1>
 
-  <refsect1>
-    <title>Notes</title>
-
-    <para><function>sd_bus_set_watch_bind()</function> and <function>sd_bus_get_watch_bind()</function> are available as
-    a shared library, which can be compiled and linked to with the <constant>libsystemd</constant> <citerefentry
-    project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> file.</para>
-  </refsect1>
+  <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml
index 95af2c1ee..c5704f53a 100644
--- a/man/sd_journal_enumerate_fields.xml
+++ b/man/sd_journal_enumerate_fields.xml
@@ -86,8 +86,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict" />
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml
index ce37e177b..80edc08c8 100644
--- a/man/sd_journal_get_catalog.xml
+++ b/man/sd_journal_get_catalog.xml
@@ -87,9 +87,14 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a
-    single thread may operate on a given <structname>sd_journal</structname> object. Function
-    <function>sd_journal_get_catalog_for_message_id()</function> is thread-safe.</para>
+    <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only
+    a single specific thread may operate on a given object during its entire lifetime. It's safe to allocate multiple
+    independent objects and use each from a specific thread in parallel. However, it's not safe to allocate such an
+    object in one thread, and operate or free it from any other, even if locking is used to ensure these threads don't
+    operate on it at the very same time.</para>
+
+    <para>Function <function>sd_journal_get_catalog_for_message_id()</function> is are thread-safe and may be called in
+    parallel from multiple threads.</para>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
index 6817a3cd5..d5e465b81 100644
--- a/man/sd_journal_get_cursor.xml
+++ b/man/sd_journal_get_cursor.xml
@@ -98,8 +98,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict" />
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml
index dc8e32bf8..b2a0634f7 100644
--- a/man/sd_journal_get_cutoff_realtime_usec.xml
+++ b/man/sd_journal_get_cutoff_realtime_usec.xml
@@ -96,8 +96,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict" />
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml
index 99f950044..464fd16ac 100644
--- a/man/sd_journal_get_data.xml
+++ b/man/sd_journal_get_data.xml
@@ -156,7 +156,13 @@
     success or a negative errno-style error code.</para>
   </refsect1>
 
-  <xi:include href="libsystemd-pkgconfig.xml" />
+  <refsect1>
+    <title>Notes</title>
+
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
+
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+  </refsect1>
 
   <refsect1>
     <title>Examples</title>
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
index 7edbc4bc2..2186b685b 100644
--- a/man/sd_journal_get_fd.xml
+++ b/man/sd_journal_get_fd.xml
@@ -226,14 +226,9 @@ else {
   <refsect1>
     <title>Notes</title>
 
-    <para>The <function>sd_journal_get_fd()</function>,
-    <function>sd_journal_get_events()</function>,
-    <function>sd_journal_reliable_fd()</function>,
-    <function>sd_journal_process()</function> and
-    <function>sd_journal_wait()</function> interfaces are available as
-    a shared library, which can be compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
+
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml
index 2030e8372..e0f5c4d2e 100644
--- a/man/sd_journal_get_realtime_usec.xml
+++ b/man/sd_journal_get_realtime_usec.xml
@@ -89,7 +89,13 @@
     <function>sd_journal_get_monotonic_usec()</function>.</para>
   </refsect1>
 
-  <xi:include href="libsystemd-pkgconfig.xml" />
+  <refsect1>
+    <title>Notes</title>
+
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
+
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
+  </refsect1>
 
   <refsect1>
     <title>See Also</title>
diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml
index 358a62d06..39f53dd5e 100644
--- a/man/sd_journal_get_usage.xml
+++ b/man/sd_journal_get_usage.xml
@@ -56,8 +56,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml
index b7bbf224d..44fdc8d18 100644
--- a/man/sd_journal_has_runtime_files.xml
+++ b/man/sd_journal_has_runtime_files.xml
@@ -66,8 +66,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
index c0ca5a8a1..9a27d1426 100644
--- a/man/sd_journal_next.xml
+++ b/man/sd_journal_next.xml
@@ -122,8 +122,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml
index 9f600b223..cf787b7ea 100644
--- a/man/sd_journal_open.xml
+++ b/man/sd_journal_open.xml
@@ -6,7 +6,8 @@
   SPDX-License-Identifier: LGPL-2.1+
 -->
 
-<refentry id="sd_journal_open">
+<refentry id="sd_journal_open"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
 
   <refentryinfo>
     <title>sd_journal_open</title>
@@ -184,15 +185,9 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
-    <para>The <function>sd_journal_open()</function>,
-    <function>sd_journal_open_directory()</function> and
-    <function>sd_journal_close()</function> interfaces are available
-    as a shared library, which can be compiled and linked to with the
-    <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    file.</para>
+    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
 
   <refsect1>
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
index f8ff7ba09..e18cf88bb 100644
--- a/man/sd_journal_print.xml
+++ b/man/sd_journal_print.xml
@@ -177,7 +177,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
 
   <refsect1>
     <title>Thread safety</title>
-    <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>
+
+    <xi:include href="threads-aware.xml" xpointer="safe"/>
 
     <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry
     project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml
index c62f333ea..9adafa114 100644
--- a/man/sd_journal_query_unique.xml
+++ b/man/sd_journal_query_unique.xml
@@ -126,8 +126,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml
index 86274071f..da88d241e 100644
--- a/man/sd_journal_seek_head.xml
+++ b/man/sd_journal_seek_head.xml
@@ -120,8 +120,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>All functions listed here are thread-agnostic and only a single thread may operate
-    on a given <structname>sd_journal</structname> object.</para>
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml
index de76cabb4..8e65dc765 100644
--- a/man/sd_journal_stream_fd.xml
+++ b/man/sd_journal_stream_fd.xml
@@ -92,8 +92,7 @@
   <refsect1>
     <title>Notes</title>
 
-    <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be called
-    from multiple threads.</para>
+    <xi:include href="threads-aware.xml" xpointer="safe"/>
 
     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
   </refsect1>
diff --git a/man/threads-aware.xml b/man/threads-aware.xml
new file mode 100644
index 000000000..7985f4acd
--- /dev/null
+++ b/man/threads-aware.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<!--
+  SPDX-License-Identifier: LGPL-2.1+
+-->
+
+<refsect1>
+
+<para id="strict">All functions listed here are thread-agnostic and only a single specific thread may operate on a
+given object during its entire lifetime. It's safe to allocate multiple independent objects and use each from a
+specific thread in parallel. However, it's not safe to allocate such an object in one thread, and operate or free it
+from any other, even if locking is used to ensure these threads don't operate on it at the very same time.</para>
+
+<para id="safe">All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>
+
+</refsect1>