<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
<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" />
<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>
<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>
<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>
<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>
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>
<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>
<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>
<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>
<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>
<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>
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>
<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>
<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>.
<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>
<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>
<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>
--- /dev/null
+<?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>