Skip to content

Commit 64a7ef8

Browse files
poetteringpoettering
committed
man: be more explicit about thread safety of sd_journal
Triggered by https://bugzilla.redhat.com/show_bug.cgi?id=1609349 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.
1 parent af560fc commit 64a7ef8

18 files changed

+68
-55
lines changed

‎man/libudev.xml‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,9 @@
4848
<citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
4949
It is used to track library state and link objects together. No
5050
global state is used by libudev, everything is always linked to
51-
a udev context. Furthermore, multiple different udev contexts can
52-
be used in parallel by multiple threads. However, a single context
53-
must not be accessed by multiple threads in parallel. The caller
54-
is responsible for providing suitable locking if they intend to use
55-
it from multiple threads.</para>
51+
a udev context.</para>
52+
53+
<xi:include href="threads-aware.xml" xpointer="strict"/>
5654

5755
<para>To introspect a local device on a system, a udev device
5856
object can be created via

‎man/sd-journal.xml‎

Lines changed: 8 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -77,16 +77,15 @@
7777
<refsect1>
7878
<title>Thread safety</title>
7979

80-
<para>Functions that operate on the <structname>sd_journal</structname> object are thread
81-
agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at
82-
a time, but multiple threads may use multiple such objects safely. Other functions —
83-
those that are used to send entries to the journal, like
84-
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
85-
and similar, or those that are used to retrieve global information like
86-
<citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>
87-
and
80+
<para>Functions that operate on <structname>sd_journal</structname> objects are thread agnostic — given
81+
<structname>sd_journal</structname> pointer may only be used from one specific thread at all times (and it has to
82+
be the very same one during the entire lifetime of the object), but multiple, independent threads may use multiple,
83+
independent objects safely. Other functions — those that are used to send entries to the journal, like
84+
<citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry> and similar,
85+
or those that are used to retrieve global information like
86+
<citerefentry><refentrytitle>sd_journal_stream_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
8887
<citerefentry><refentrytitle>sd_journal_get_catalog_for_message_id</refentrytitle><manvolnum>3</manvolnum></citerefentry>
89-
— are thread-safe and may be called from multiple threads in parallel.</para>
88+
— are fully thread-safe and may be called from multiple threads in parallel.</para>
9089
</refsect1>
9190

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

‎man/sd_journal_enumerate_fields.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,7 @@
8686
<refsect1>
8787
<title>Notes</title>
8888

89-
<para>All functions listed here are thread-agnostic and only a single thread may operate
90-
on a given <structname>sd_journal</structname> object.</para>
89+
<xi:include href="threads-aware.xml" xpointer="strict" />
9190

9291
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
9392
</refsect1>

‎man/sd_journal_get_catalog.xml‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -87,9 +87,14 @@
8787
<refsect1>
8888
<title>Notes</title>
8989

90-
<para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a
91-
single thread may operate on a given <structname>sd_journal</structname> object. Function
92-
<function>sd_journal_get_catalog_for_message_id()</function> is thread-safe.</para>
90+
<para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only
91+
a single specific thread may operate on a given object during its entire lifetime. It's safe to allocate multiple
92+
independent objects and use each from a specific thread in parallel. However, it's not safe to allocate such an
93+
object in one thread, and operate or free it from any other, even if locking is used to ensure these threads don't
94+
operate on it at the very same time.</para>
95+
96+
<para>Function <function>sd_journal_get_catalog_for_message_id()</function> is are thread-safe and may be called in
97+
parallel from multiple threads.</para>
9398

9499
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
95100
</refsect1>

‎man/sd_journal_get_cursor.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,7 @@
9898
<refsect1>
9999
<title>Notes</title>
100100

101-
<para>All functions listed here are thread-agnostic and only a single thread may operate
102-
on a given <structname>sd_journal</structname> object.</para>
101+
<xi:include href="threads-aware.xml" xpointer="strict" />
103102

104103
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
105104
</refsect1>

‎man/sd_journal_get_cutoff_realtime_usec.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -96,8 +96,7 @@
9696
<refsect1>
9797
<title>Notes</title>
9898

99-
<para>All functions listed here are thread-agnostic and only a single thread may operate
100-
on a given <structname>sd_journal</structname> object.</para>
99+
<xi:include href="threads-aware.xml" xpointer="strict" />
101100

102101
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
103102
</refsect1>

‎man/sd_journal_get_data.xml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,13 @@
156156
success or a negative errno-style error code.</para>
157157
</refsect1>
158158

159-
<xi:include href="libsystemd-pkgconfig.xml" />
159+
<refsect1>
160+
<title>Notes</title>
161+
162+
<xi:include href="threads-aware.xml" xpointer="strict"/>
163+
164+
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
165+
</refsect1>
160166

161167
<refsect1>
162168
<title>Examples</title>

‎man/sd_journal_get_fd.xml‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -226,14 +226,9 @@ else {
226226
<refsect1>
227227
<title>Notes</title>
228228

229-
<para>The <function>sd_journal_get_fd()</function>,
230-
<function>sd_journal_get_events()</function>,
231-
<function>sd_journal_reliable_fd()</function>,
232-
<function>sd_journal_process()</function> and
233-
<function>sd_journal_wait()</function> interfaces are available as
234-
a shared library, which can be compiled and linked to with the
235-
<constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
236-
file.</para>
229+
<xi:include href="threads-aware.xml" xpointer="strict"/>
230+
231+
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
237232
</refsect1>
238233

239234
<refsect1>

‎man/sd_journal_get_realtime_usec.xml‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,13 @@
8989
<function>sd_journal_get_monotonic_usec()</function>.</para>
9090
</refsect1>
9191

92-
<xi:include href="libsystemd-pkgconfig.xml" />
92+
<refsect1>
93+
<title>Notes</title>
94+
95+
<xi:include href="threads-aware.xml" xpointer="strict"/>
96+
97+
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
98+
</refsect1>
9399

94100
<refsect1>
95101
<title>See Also</title>

‎man/sd_journal_get_usage.xml‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,7 @@
5656
<refsect1>
5757
<title>Notes</title>
5858

59-
<para>All functions listed here are thread-agnostic and only a single thread may operate
60-
on a given <structname>sd_journal</structname> object.</para>
59+
<xi:include href="threads-aware.xml" xpointer="strict"/>
6160

6261
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
6362
</refsect1>

0 commit comments

Comments
 (0)