You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
396 lines
15 KiB
396 lines
15 KiB
5 years ago
|
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 @@
|
||
|
|
+<?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>
|