daandemeyer / rpms / systemd

Forked from rpms/systemd 2 years ago
Clone
c62b8e
From dd004bcc058dbb7c66b8eb1a728732ccfce746c7 Mon Sep 17 00:00:00 2001
c62b8e
From: Jan Synacek <jsynacek@redhat.com>
c62b8e
Date: Tue, 5 Mar 2019 10:45:07 +0100
c62b8e
Subject: [PATCH] man: be more explicit about thread safety of sd_journal
c62b8e
c62b8e
This adds two generic paragaphs we include via xinclude. One is the
c62b8e
"strict" version, which contains wording saying that we are thread
c62b8e
agnostic and what that means. And the other is the "safe" version, for
c62b8e
the cases we provide fully safety.
c62b8e
c62b8e
Let's then change most man pages to use either of these generic
c62b8e
paragraphs. With one exception: man/sd_journal_get_catalog.xml contains
c62b8e
both kinds of function, we hence use manual wording.
c62b8e
c62b8e
(cherry picked from commit 64a7ef8bc06b5dcfcd9f99ea10a43bde75c4370f)
c62b8e
c62b8e
Related: #1609349
c62b8e
---
c62b8e
 man/sd-journal.xml                          | 14 ++++++++++++++
c62b8e
 man/sd_journal_get_catalog.xml              |  9 +++++++++
c62b8e
 man/sd_journal_get_cursor.xml               |  4 +++-
c62b8e
 man/sd_journal_get_cutoff_realtime_usec.xml |  4 +++-
c62b8e
 man/sd_journal_get_data.xml                 |  4 +++-
c62b8e
 man/sd_journal_get_fd.xml                   |  4 +++-
c62b8e
 man/sd_journal_get_realtime_usec.xml        |  4 +++-
c62b8e
 man/sd_journal_get_usage.xml                |  4 +++-
c62b8e
 man/sd_journal_has_runtime_files.xml        |  8 +++++++-
c62b8e
 man/sd_journal_next.xml                     |  4 +++-
c62b8e
 man/sd_journal_open.xml                     |  4 +++-
c62b8e
 man/sd_journal_print.xml                    |  4 +++-
c62b8e
 man/sd_journal_query_unique.xml             |  4 +++-
c62b8e
 man/sd_journal_seek_head.xml                |  4 +++-
c62b8e
 man/sd_journal_stream_fd.xml                |  4 +++-
c62b8e
 man/threads-aware.xml                       | 17 +++++++++++++++++
c62b8e
 16 files changed, 83 insertions(+), 13 deletions(-)
c62b8e
 create mode 100644 man/threads-aware.xml
c62b8e
c62b8e
diff --git a/man/sd-journal.xml b/man/sd-journal.xml
c62b8e
index a1185d372b..11af4cd9b9 100644
c62b8e
--- a/man/sd-journal.xml
c62b8e
+++ b/man/sd-journal.xml
c62b8e
@@ -97,6 +97,20 @@
c62b8e
     tool.</para>
c62b8e
   </refsect1>
c62b8e
 
c62b8e
+  <refsect1>
c62b8e
+    <title>Thread safety</title>
c62b8e
+
c62b8e
+    <para>Functions that operate on <structname>sd_journal</structname> objects are thread agnostic — given
c62b8e
+    <structname>sd_journal</structname> pointer may only be used from one specific thread at all times (and it has to
c62b8e
+    be the very same one during the entire lifetime of the object), but multiple, independent threads may use multiple,
c62b8e
+    independent objects safely. Other functions — those that are used to send entries to the journal, like
c62b8e
+    <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar,
c62b8e
+    or those that are used to retrieve global information like
c62b8e
+    <citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
c62b8e
+    <citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>
c62b8e
+    are fully thread-safe and may be called from multiple threads in parallel.</para>
c62b8e
+  </refsect1>
c62b8e
+
c62b8e
   <xi:include href="libsystemd-pkgconfig.xml" />
c62b8e
 
c62b8e
   <refsect1>
c62b8e
diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml
c62b8e
index c19eb11b20..86eb659fe5 100644
c62b8e
--- a/man/sd_journal_get_catalog.xml
c62b8e
+++ b/man/sd_journal_get_catalog.xml
c62b8e
@@ -112,6 +112,15 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only
c62b8e
+    a single specific thread may operate on a given object during its entire lifetime. It's safe to allocate multiple
c62b8e
+    independent objects and use each from a specific thread in parallel. However, it's not safe to allocate such an
c62b8e
+    object in one thread, and operate or free it from any other, even if locking is used to ensure these threads don't
c62b8e
+    operate on it at the very same time.</para>
c62b8e
+
c62b8e
+    <para>Function <function>sd_journal_get_catalog_for_message_id()</function> is are thread-safe and may be called in
c62b8e
+    parallel from multiple threads.</para>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_catalog()</function> and
c62b8e
     <function>sd_journal_get_catalog_for_message_id()</function>
c62b8e
     interfaces are available as a shared library, which can be
c62b8e
diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml
c62b8e
index a400d8b1b5..0a20c36146 100644
c62b8e
--- a/man/sd_journal_get_cursor.xml
c62b8e
+++ b/man/sd_journal_get_cursor.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_cursor">
c62b8e
+<refentry id="sd_journal_get_cursor" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_cursor</title>
c62b8e
@@ -122,6 +122,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict" />
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_cursor()</function> and
c62b8e
     <function>sd_journal_test_cursor()</function> interfaces are
c62b8e
     available as a shared library, which can be compiled and linked to
c62b8e
diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml
c62b8e
index 23e7cc65e8..782228009d 100644
c62b8e
--- a/man/sd_journal_get_cutoff_realtime_usec.xml
c62b8e
+++ b/man/sd_journal_get_cutoff_realtime_usec.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_cutoff_realtime_usec">
c62b8e
+<refentry id="sd_journal_get_cutoff_realtime_usec" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_cutoff_realtime_usec</title>
c62b8e
@@ -120,6 +120,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict" />
c62b8e
+
c62b8e
     <para>The
c62b8e
     <function>sd_journal_get_cutoff_realtime_usec()</function> and
c62b8e
     <function>sd_journal_get_cutoff_monotonic_usec()</function>
c62b8e
diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml
c62b8e
index 1afbd7371c..dce421795a 100644
c62b8e
--- a/man/sd_journal_get_data.xml
c62b8e
+++ b/man/sd_journal_get_data.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_data">
c62b8e
+<refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_data</title>
c62b8e
@@ -183,6 +183,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_data()</function>,
c62b8e
     <function>sd_journal_enumerate_data()</function>,
c62b8e
     <function>sd_journal_restart_data()</function>,
c62b8e
diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml
c62b8e
index 3a38f733ab..a96857d0df 100644
c62b8e
--- a/man/sd_journal_get_fd.xml
c62b8e
+++ b/man/sd_journal_get_fd.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_fd">
c62b8e
+<refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_fd</title>
c62b8e
@@ -231,6 +231,8 @@ else {
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_fd()</function>,
c62b8e
     <function>sd_journal_get_events()</function>,
c62b8e
     <function>sd_journal_reliable_fd()</function>,
c62b8e
diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml
c62b8e
index 607d74666b..b67e4d6c2d 100644
c62b8e
--- a/man/sd_journal_get_realtime_usec.xml
c62b8e
+++ b/man/sd_journal_get_realtime_usec.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_realtime_usec">
c62b8e
+<refentry id="sd_journal_get_realtime_usec" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_realtime_usec</title>
c62b8e
@@ -115,6 +115,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_realtime_usec()</function> and
c62b8e
     <function>sd_journal_get_monotonic_usec()</function> interfaces
c62b8e
     are available as a shared library, which can be compiled and
c62b8e
diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml
c62b8e
index 72c804d834..6281bc850d 100644
c62b8e
--- a/man/sd_journal_get_usage.xml
c62b8e
+++ b/man/sd_journal_get_usage.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_get_usage">
c62b8e
+<refentry id="sd_journal_get_usage" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_get_usage</title>
c62b8e
@@ -80,6 +80,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_get_usage()</function> interface is
c62b8e
     available as a shared library, which can be compiled and linked to
c62b8e
     with the
c62b8e
diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml
c62b8e
index 237e649206..4dff3c67d0 100644
c62b8e
--- a/man/sd_journal_has_runtime_files.xml
c62b8e
+++ b/man/sd_journal_has_runtime_files.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_has_runtime_files">
c62b8e
+<refentry id="sd_journal_has_runtime_files" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_has_runtime_files</title>
c62b8e
@@ -85,6 +85,12 @@
c62b8e
     </para>
c62b8e
   </refsect1>
c62b8e
 
c62b8e
+  <refsect1>
c62b8e
+    <title>Notes</title>
c62b8e
+
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+  </refsect1>
c62b8e
+
c62b8e
   <refsect1>
c62b8e
     <title>See Also</title>
c62b8e
     <para>
c62b8e
diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml
c62b8e
index 115fe26661..c8664994ce 100644
c62b8e
--- a/man/sd_journal_next.xml
c62b8e
+++ b/man/sd_journal_next.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_next">
c62b8e
+<refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_next</title>
c62b8e
@@ -146,6 +146,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_next()</function>,
c62b8e
     <function>sd_journal_previous()</function>,
c62b8e
     <function>sd_journal_next_skip()</function> and
c62b8e
diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml
c62b8e
index fb572802a3..c3044670de 100644
c62b8e
--- a/man/sd_journal_open.xml
c62b8e
+++ b/man/sd_journal_open.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_open">
c62b8e
+<refentry id="sd_journal_open" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_open</title>
c62b8e
@@ -196,6 +196,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_open()</function>,
c62b8e
     <function>sd_journal_open_directory()</function> and
c62b8e
     <function>sd_journal_close()</function> interfaces are available
c62b8e
diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml
c62b8e
index 0cd0b45b9a..50ad5de7be 100644
c62b8e
--- a/man/sd_journal_print.xml
c62b8e
+++ b/man/sd_journal_print.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_print">
c62b8e
+<refentry id="sd_journal_print" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_print</title>
c62b8e
@@ -232,6 +232,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="safe"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_print()</function>,
c62b8e
     <function>sd_journal_printv()</function>,
c62b8e
     <function>sd_journal_send()</function> and
c62b8e
diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml
c62b8e
index ac0e5f633f..074dfd6789 100644
c62b8e
--- a/man/sd_journal_query_unique.xml
c62b8e
+++ b/man/sd_journal_query_unique.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_query_unique">
c62b8e
+<refentry id="sd_journal_query_unique" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_query_unique</title>
c62b8e
@@ -145,6 +145,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_query_unique()</function>,
c62b8e
     <function>sd_journal_enumerate_unique()</function> and
c62b8e
     <function>sd_journal_restart_unique()</function> interfaces are
c62b8e
diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml
c62b8e
index d74c2d5bbc..8bbbb22a73 100644
c62b8e
--- a/man/sd_journal_seek_head.xml
c62b8e
+++ b/man/sd_journal_seek_head.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_seek_head">
c62b8e
+<refentry id="sd_journal_seek_head" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_seek_head</title>
c62b8e
@@ -144,6 +144,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="strict"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_seek_head()</function>,
c62b8e
     <function>sd_journal_seek_tail()</function>,
c62b8e
     <function>sd_journal_seek_monotonic_usec()</function>,
c62b8e
diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml
c62b8e
index 2ea7731b48..340760ba36 100644
c62b8e
--- a/man/sd_journal_stream_fd.xml
c62b8e
+++ b/man/sd_journal_stream_fd.xml
c62b8e
@@ -21,7 +21,7 @@
c62b8e
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
c62b8e
 -->
c62b8e
 
c62b8e
-<refentry id="sd_journal_stream_fd">
c62b8e
+<refentry id="sd_journal_stream_fd" xmlns:xi="http://www.w3.org/2001/XInclude">
c62b8e
 
c62b8e
   <refentryinfo>
c62b8e
     <title>sd_journal_stream_fd</title>
c62b8e
@@ -104,6 +104,8 @@
c62b8e
   <refsect1>
c62b8e
     <title>Notes</title>
c62b8e
 
c62b8e
+    <xi:include href="threads-aware.xml" xpointer="safe"/>
c62b8e
+
c62b8e
     <para>The <function>sd_journal_stream_fd()</function> interface is
c62b8e
     available as a shared library, which can be compiled and linked to
c62b8e
     with the
c62b8e
diff --git a/man/threads-aware.xml b/man/threads-aware.xml
c62b8e
new file mode 100644
c62b8e
index 0000000000..7985f4acd1
c62b8e
--- /dev/null
c62b8e
+++ b/man/threads-aware.xml
c62b8e
@@ -0,0 +1,17 @@
c62b8e
+
c62b8e
+
c62b8e
+
c62b8e
+
c62b8e
+  SPDX-License-Identifier: LGPL-2.1+
c62b8e
+-->
c62b8e
+
c62b8e
+<refsect1>
c62b8e
+
c62b8e
+<para id="strict">All functions listed here are thread-agnostic and only a single specific thread may operate on a
c62b8e
+given object during its entire lifetime. It's safe to allocate multiple independent objects and use each from a
c62b8e
+specific thread in parallel. However, it's not safe to allocate such an object in one thread, and operate or free it
c62b8e
+from any other, even if locking is used to ensure these threads don't operate on it at the very same time.</para>
c62b8e
+
c62b8e
+<para id="safe">All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>
c62b8e
+
c62b8e
+</refsect1>