From dd004bcc058dbb7c66b8eb1a728732ccfce746c7 Mon Sep 17 00:00:00 2001

From: Jan Synacek <jsynacek@redhat.com>

Date: Tue, 5 Mar 2019 10:45:07 +0100

Subject: [PATCH] man: be more explicit about thread safety of sd_journal

This adds two generic paragaphs we include via xinclude. One is the

"strict" version, which contains wording saying that we are thread

agnostic and what that means. And the other is the "safe" version, for

the cases we provide fully safety.

Let's then change most man pages to use either of these generic

paragraphs. With one exception: man/sd_journal_get_catalog.xml contains

both kinds of function, we hence use manual wording.

(cherry picked from commit 64a7ef8bc06b5dcfcd9f99ea10a43bde75c4370f)

Related: #1609349

---

 man/sd-journal.xml                          | 14 ++++++++++++++

 man/sd_journal_get_catalog.xml              |  9 +++++++++

 man/sd_journal_get_cursor.xml               |  4 +++-

 man/sd_journal_get_cutoff_realtime_usec.xml |  4 +++-

 man/sd_journal_get_data.xml                 |  4 +++-

 man/sd_journal_get_fd.xml                   |  4 +++-

 man/sd_journal_get_realtime_usec.xml        |  4 +++-

 man/sd_journal_get_usage.xml                |  4 +++-

 man/sd_journal_has_runtime_files.xml        |  8 +++++++-

 man/sd_journal_next.xml                     |  4 +++-

 man/sd_journal_open.xml                     |  4 +++-

 man/sd_journal_print.xml                    |  4 +++-

 man/sd_journal_query_unique.xml             |  4 +++-

 man/sd_journal_seek_head.xml                |  4 +++-

 man/sd_journal_stream_fd.xml                |  4 +++-

 man/threads-aware.xml                       | 17 +++++++++++++++++

 16 files changed, 83 insertions(+), 13 deletions(-)

 create mode 100644 man/threads-aware.xml

diff --git a/man/sd-journal.xml b/man/sd-journal.xml

index a1185d372b..11af4cd9b9 100644

--- a/man/sd-journal.xml

+++ b/man/sd-journal.xml

@@ -97,6 +97,20 @@

     tool.</para>

   </refsect1>

+  <refsect1>

+    <title>Thread safety</title>

+

+    <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 fully thread-safe and may be called from multiple threads in parallel.</para>

+  </refsect1>

+

   <xi:include href="libsystemd-pkgconfig.xml" />

   <refsect1>

diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml

index c19eb11b20..86eb659fe5 100644

--- a/man/sd_journal_get_catalog.xml

+++ b/man/sd_journal_get_catalog.xml

@@ -112,6 +112,15 @@

   <refsect1>

     <title>Notes</title>

+    <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>

+

     <para>The <function>sd_journal_get_catalog()</function> and

     <function>sd_journal_get_catalog_for_message_id()</function>

     interfaces are available as a shared library, which can be

diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml

index a400d8b1b5..0a20c36146 100644

--- a/man/sd_journal_get_cursor.xml

+++ b/man/sd_journal_get_cursor.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_cursor">

+<refentry id="sd_journal_get_cursor" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_cursor</title>

@@ -122,6 +122,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict" />

+

     <para>The <function>sd_journal_get_cursor()</function> and

     <function>sd_journal_test_cursor()</function> interfaces are

     available as a shared library, which can be compiled and linked to

diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml

index 23e7cc65e8..782228009d 100644

--- a/man/sd_journal_get_cutoff_realtime_usec.xml

+++ b/man/sd_journal_get_cutoff_realtime_usec.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_cutoff_realtime_usec">

+<refentry id="sd_journal_get_cutoff_realtime_usec" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_cutoff_realtime_usec</title>

@@ -120,6 +120,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict" />

+

     <para>The

     <function>sd_journal_get_cutoff_realtime_usec()</function> and

     <function>sd_journal_get_cutoff_monotonic_usec()</function>

diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml

index 1afbd7371c..dce421795a 100644

--- a/man/sd_journal_get_data.xml

+++ b/man/sd_journal_get_data.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_data">

+<refentry id="sd_journal_get_data" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_data</title>

@@ -183,6 +183,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_get_data()</function>,

     <function>sd_journal_enumerate_data()</function>,

     <function>sd_journal_restart_data()</function>,

diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml

index 3a38f733ab..a96857d0df 100644

--- a/man/sd_journal_get_fd.xml

+++ b/man/sd_journal_get_fd.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_fd">

+<refentry id="sd_journal_get_fd" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_fd</title>

@@ -231,6 +231,8 @@ else {

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_get_fd()</function>,

     <function>sd_journal_get_events()</function>,

     <function>sd_journal_reliable_fd()</function>,

diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml

index 607d74666b..b67e4d6c2d 100644

--- a/man/sd_journal_get_realtime_usec.xml

+++ b/man/sd_journal_get_realtime_usec.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_realtime_usec">

+<refentry id="sd_journal_get_realtime_usec" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_realtime_usec</title>

@@ -115,6 +115,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_get_realtime_usec()</function> and

     <function>sd_journal_get_monotonic_usec()</function> interfaces

     are available as a shared library, which can be compiled and

diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml

index 72c804d834..6281bc850d 100644

--- a/man/sd_journal_get_usage.xml

+++ b/man/sd_journal_get_usage.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_get_usage">

+<refentry id="sd_journal_get_usage" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_get_usage</title>

@@ -80,6 +80,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_get_usage()</function> interface is

     available as a shared library, which can be compiled and linked to

     with the

diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml

index 237e649206..4dff3c67d0 100644

--- a/man/sd_journal_has_runtime_files.xml

+++ b/man/sd_journal_has_runtime_files.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_has_runtime_files">

+<refentry id="sd_journal_has_runtime_files" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_has_runtime_files</title>

@@ -85,6 +85,12 @@

     </para>

   </refsect1>

+  <refsect1>

+    <title>Notes</title>

+

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+  </refsect1>

+

   <refsect1>

     <title>See Also</title>

     <para>

diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml

index 115fe26661..c8664994ce 100644

--- a/man/sd_journal_next.xml

+++ b/man/sd_journal_next.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_next">

+<refentry id="sd_journal_next" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_next</title>

@@ -146,6 +146,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_next()</function>,

     <function>sd_journal_previous()</function>,

     <function>sd_journal_next_skip()</function> and

diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml

index fb572802a3..c3044670de 100644

--- a/man/sd_journal_open.xml

+++ b/man/sd_journal_open.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_open">

+<refentry id="sd_journal_open" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_open</title>

@@ -196,6 +196,8 @@

   <refsect1>

     <title>Notes</title>

+    <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

diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml

index 0cd0b45b9a..50ad5de7be 100644

--- a/man/sd_journal_print.xml

+++ b/man/sd_journal_print.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_print">

+<refentry id="sd_journal_print" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_print</title>

@@ -232,6 +232,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid(

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="safe"/>

+

     <para>The <function>sd_journal_print()</function>,

     <function>sd_journal_printv()</function>,

     <function>sd_journal_send()</function> and

diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml

index ac0e5f633f..074dfd6789 100644

--- a/man/sd_journal_query_unique.xml

+++ b/man/sd_journal_query_unique.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_query_unique">

+<refentry id="sd_journal_query_unique" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_query_unique</title>

@@ -145,6 +145,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_query_unique()</function>,

     <function>sd_journal_enumerate_unique()</function> and

     <function>sd_journal_restart_unique()</function> interfaces are

diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml

index d74c2d5bbc..8bbbb22a73 100644

--- a/man/sd_journal_seek_head.xml

+++ b/man/sd_journal_seek_head.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_seek_head">

+<refentry id="sd_journal_seek_head" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_seek_head</title>

@@ -144,6 +144,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="strict"/>

+

     <para>The <function>sd_journal_seek_head()</function>,

     <function>sd_journal_seek_tail()</function>,

     <function>sd_journal_seek_monotonic_usec()</function>,

diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml

index 2ea7731b48..340760ba36 100644

--- a/man/sd_journal_stream_fd.xml

+++ b/man/sd_journal_stream_fd.xml

@@ -21,7 +21,7 @@

   along with systemd; If not, see <http://www.gnu.org/licenses/>.

 -->

-<refentry id="sd_journal_stream_fd">

+<refentry id="sd_journal_stream_fd" xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>

     <title>sd_journal_stream_fd</title>

@@ -104,6 +104,8 @@

   <refsect1>

     <title>Notes</title>

+    <xi:include href="threads-aware.xml" xpointer="safe"/>

+

     <para>The <function>sd_journal_stream_fd()</function> interface is

     available as a shared library, which can be compiled and linked to

     with the

diff --git a/man/threads-aware.xml b/man/threads-aware.xml

new file mode 100644

index 0000000000..7985f4acd1

--- /dev/null

+++ b/man/threads-aware.xml

@@ -0,0 +1,17 @@

+

+

+

+

+  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>