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 @@ udev_new3. 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. + a udev context. + + 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 @@ Thread safety - Functions that operate on the sd_journal object are thread - agnostic — given sd_journal 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 - sd_journal_print3 - and similar, or those that are used to retrieve global information like - sd_journal_stream_fd3 - and + Functions that operate on sd_journal objects are thread agnostic — given + sd_journal 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 + sd_journal_print3 and similar, + or those that are used to retrieve global information like + sd_journal_stream_fd3 and sd_journal_get_catalog_for_message_id3 - — are thread-safe and may be called from multiple threads in parallel. + — are fully thread-safe and may be called from multiple threads in parallel. 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - Function sd_journal_get_catalog() is thread-agnostic and only a - single thread may operate on a given sd_journal object. Function - sd_journal_get_catalog_for_message_id() is thread-safe. + Function sd_journal_get_catalog() 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. + + Function sd_journal_get_catalog_for_message_id() is are thread-safe and may be called in + parallel from multiple threads. 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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. - + + Notes + + + + + Examples 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 { Notes - The sd_journal_get_fd(), - sd_journal_get_events(), - sd_journal_reliable_fd(), - sd_journal_process() and - sd_journal_wait() interfaces are available as - a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 - file. + + + 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 @@ sd_journal_get_monotonic_usec(). - + + Notes + + + + + See Also 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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+ --> - + sd_journal_open @@ -184,15 +185,9 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + - The sd_journal_open(), - sd_journal_open_directory() and - sd_journal_close() interfaces are available - as a shared library, which can be compiled and linked to with the - libsystemd pkg-config1 - file. + 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( Thread safety - All functions listed here are thread-safe and may be called in parallel from multiple threads. + + sd_journal_sendv() is "async signal safe" in the meaning of signal-safety7. 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - All functions listed here are thread-agnostic and only a single thread may operate - on a given sd_journal object. + 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 @@ Notes - Function sd_journal_stream_fd() is thread-safe and may be called - from multiple threads. + 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 @@ + + + + + + + +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. + +All functions listed here are thread-safe and may be called in parallel from multiple threads. + +