morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

man: fix advice regarding thread safety of libsystemd

Browse Source 
The prohibition to move libsystemd objects between threads was added in
64a7ef8bc0 ('man: be more explicit about thread
safety of sd_journal'). At the time, this was valid, because we were using the
mempool for allocation and it apparently didn't handle access from different
threads. Sadlly, the commit links to a bugzilla entry referenced in the commit
is not publicly visible anymore, so the details are murky. But we stopped using
the mempool in a5d8835c78 ('mempool: only enable
mempool use when linked to libsystemd-shared.so'), with subsequent followup in
b01f31954f ('Turn mempool_enabled() into a weak
symbol'). The restriction added in the man page is not necessary since then.

The text in the man page was arguably incorrect in calling the code
"thread-agnostic". If the code does not support being touched from threads at
all and has global state to tied to the main thread, it is not "agnostic", but
just doesn't support threads.

(I'm looking into https://github.com/systemd/python-systemd/issues/143, and
with the current scheme, the python-systemd module and all python code using
libsystemd would be very hard to use. With the change to free-threaded python
in python3.13, i.e. the replacement of single Global Interpreter Lock by
locking on individual objects, this limitation would become even more
constraining.)
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
2025-10-03 13:17:32 +02:00
committed by Yu Watanabe
parent 5fc94cc6d9
commit 4a3620c55a
3 changed files with 16 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
man/sd-journal.xml
View File

@@ -75,13 +75,14 @@
<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
<para>Functions that operate on <structname>sd_journal</structname> objects are thread agnostic — a given
<structname>sd_journal</structname> pointer may only be used from one thread at a time, but multiple
independent threads may use multiple objects concurrently. Some 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>

12
man/sd_journal_get_catalog.xml
View File

@@ -84,14 +84,12 @@
<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 is safe to allocate multiple
independent objects and use each from a specific thread in parallel. However, it is 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 do not
operate on it at the very same time.</para>
<para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a single thread
may operate on a given object at any given time. Multiple independent objects may be used from different
threads in parallel.</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>Function <function>sd_journal_get_catalog_for_message_id()</function> is thread-safe and may be
called from multiple threads in parallel.</para>
<xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
</refsect1>

7
man/threads-aware.xml
View File

@@ -6,10 +6,9 @@
<refsect1>
<title/>
<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 is safe to allocate multiple independent objects and use each from a
specific thread in parallel. However, it is 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 do not operate on it at the very same time.</para>
<para id="strict">All functions listed here are thread-agnostic and only a single thread may operate on a
given object at any given time. Different threads may access the same object at different times. Multiple
independent objects may be used from different threads in parallel.</para>
<para id="safe">All functions listed here are thread-safe and may be called in parallel from multiple threads.</para>