diff options
| -rw-r--r-- | man/libudev.xml | 8 | ||||
| -rw-r--r-- | man/sd-journal.xml | 17 | ||||
| -rw-r--r-- | man/sd_journal_enumerate_fields.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_get_catalog.xml | 11 | ||||
| -rw-r--r-- | man/sd_journal_get_cursor.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_get_cutoff_realtime_usec.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_get_data.xml | 8 | ||||
| -rw-r--r-- | man/sd_journal_get_fd.xml | 11 | ||||
| -rw-r--r-- | man/sd_journal_get_realtime_usec.xml | 8 | ||||
| -rw-r--r-- | man/sd_journal_get_usage.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_has_runtime_files.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_next.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_open.xml | 13 | ||||
| -rw-r--r-- | man/sd_journal_print.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_query_unique.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_seek_head.xml | 3 | ||||
| -rw-r--r-- | man/sd_journal_stream_fd.xml | 3 | ||||
| -rw-r--r-- | man/threads-aware.xml | 17 |
18 files changed, 68 insertions, 55 deletions
diff --git a/man/libudev.xml b/man/libudev.xml index 8cb4ba59fc..382c1aa25c 100644 --- a/man/libudev.xml +++ b/man/libudev.xml @@ -48,11 +48,9 @@ <citerefentry><refentrytitle>udev_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>. It is used to track library state and link objects together. No global state is used by libudev, everything is always linked to - a udev context. Furthermore, multiple different udev contexts can - be used in parallel by multiple threads. However, a single context - must not be accessed by multiple threads in parallel. The caller - is responsible for providing suitable locking if they intend to use - it from multiple threads.</para> + a udev context.</para> + + <xi:include href="threads-aware.xml" xpointer="strict"/> <para>To introspect a local device on a system, a udev device object can be created via diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 8bfcb90ca0..3fa6c75b7e 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -77,16 +77,15 @@ <refsect1> <title>Thread safety</title> - <para>Functions that operate on the <structname>sd_journal</structname> object are thread - agnostic — given <structname>sd_journal</structname> pointer may only be used from one thread at - a time, but multiple threads may use multiple such 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 — 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 thread-safe and may be called from multiple threads in parallel.</para> + — are fully thread-safe and may be called from multiple threads in parallel.</para> </refsect1> <xi:include href="libsystemd-pkgconfig.xml" /> diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml index 95af2c1ee0..c5704f53ad 100644 --- a/man/sd_journal_enumerate_fields.xml +++ b/man/sd_journal_enumerate_fields.xml @@ -86,8 +86,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml index ce37e177bd..80edc08c81 100644 --- a/man/sd_journal_get_catalog.xml +++ b/man/sd_journal_get_catalog.xml @@ -87,9 +87,14 @@ <refsect1> <title>Notes</title> - <para>Function <function>sd_journal_get_catalog()</function> is thread-agnostic and only a - single thread may operate on a given <structname>sd_journal</structname> object. Function - <function>sd_journal_get_catalog_for_message_id()</function> is thread-safe.</para> + <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> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index 6817a3cd54..d5e465b81a 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -98,8 +98,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index dc8e32bf81..b2a0634f7d 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -96,8 +96,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict" /> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 99f9500441..464fd16ace 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -156,7 +156,13 @@ success or a negative errno-style error code.</para> </refsect1> - <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </refsect1> <refsect1> <title>Examples</title> diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 7edbc4bc25..2186b685bf 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -226,14 +226,9 @@ else { <refsect1> <title>Notes</title> - <para>The <function>sd_journal_get_fd()</function>, - <function>sd_journal_get_events()</function>, - <function>sd_journal_reliable_fd()</function>, - <function>sd_journal_process()</function> and - <function>sd_journal_wait()</function> interfaces are available as - a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> <refsect1> diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index 2030e8372d..e0f5c4d2e9 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -89,7 +89,13 @@ <function>sd_journal_get_monotonic_usec()</function>.</para> </refsect1> - <xi:include href="libsystemd-pkgconfig.xml" /> + <refsect1> + <title>Notes</title> + + <xi:include href="threads-aware.xml" xpointer="strict"/> + + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> + </refsect1> <refsect1> <title>See Also</title> diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 358a62d066..39f53dd5eb 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -56,8 +56,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml index b7bbf224d4..44fdc8d186 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -66,8 +66,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index c0ca5a8a14..9a27d1426e 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -122,8 +122,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 9f600b223f..cf787b7ea1 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -6,7 +6,8 @@ SPDX-License-Identifier: LGPL-2.1+ --> -<refentry id="sd_journal_open"> +<refentry id="sd_journal_open" + xmlns:xi="http://www.w3.org/2001/XInclude"> <refentryinfo> <title>sd_journal_open</title> @@ -184,15 +185,9 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <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 - as a shared library, which can be compiled and linked to with the - <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> - file.</para> + <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> <refsect1> diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index f8ff7ba093..e18cf88bbc 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -177,7 +177,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( <refsect1> <title>Thread safety</title> - <para>All functions listed here are thread-safe and may be called in parallel from multiple threads.</para> + + <xi:include href="threads-aware.xml" xpointer="safe"/> <para><function>sd_journal_sendv()</function> is "async signal safe" in the meaning of <citerefentry project='man-pages'><refentrytitle>signal-safety</refentrytitle><manvolnum>7</manvolnum></citerefentry>. diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index c62f333eab..9adafa1144 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -126,8 +126,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index 86274071f5..da88d241e8 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -120,8 +120,7 @@ <refsect1> <title>Notes</title> - <para>All functions listed here are thread-agnostic and only a single thread may operate - on a given <structname>sd_journal</structname> object.</para> + <xi:include href="threads-aware.xml" xpointer="strict"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index de76cabb4d..8e65dc7658 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -92,8 +92,7 @@ <refsect1> <title>Notes</title> - <para>Function <function>sd_journal_stream_fd()</function> is thread-safe and may be called - from multiple threads.</para> + <xi:include href="threads-aware.xml" xpointer="safe"/> <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/> </refsect1> 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> |