From dd004bcc058dbb7c66b8eb1a728732ccfce746c7 Mon Sep 17 00:00:00 2001 From: Jan Synacek Date: Tue, 5 Mar 2019 10:45:07 +0100 Subject: [PATCH] man: be more explicit about thread safety of sd_journal 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. (cherry picked from commit 64a7ef8bc06b5dcfcd9f99ea10a43bde75c4370f) Related: #1609349 --- man/sd-journal.xml | 14 ++++++++++++++ man/sd_journal_get_catalog.xml | 9 +++++++++ man/sd_journal_get_cursor.xml | 4 +++- man/sd_journal_get_cutoff_realtime_usec.xml | 4 +++- man/sd_journal_get_data.xml | 4 +++- man/sd_journal_get_fd.xml | 4 +++- man/sd_journal_get_realtime_usec.xml | 4 +++- man/sd_journal_get_usage.xml | 4 +++- man/sd_journal_has_runtime_files.xml | 8 +++++++- man/sd_journal_next.xml | 4 +++- man/sd_journal_open.xml | 4 +++- man/sd_journal_print.xml | 4 +++- man/sd_journal_query_unique.xml | 4 +++- man/sd_journal_seek_head.xml | 4 +++- man/sd_journal_stream_fd.xml | 4 +++- man/threads-aware.xml | 17 +++++++++++++++++ 16 files changed, 83 insertions(+), 13 deletions(-) create mode 100644 man/threads-aware.xml diff --git a/man/sd-journal.xml b/man/sd-journal.xml index a1185d372b..11af4cd9b9 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -97,6 +97,20 @@ tool. + + Thread safety + + 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 fully thread-safe and may be called from multiple threads in parallel. + + diff --git a/man/sd_journal_get_catalog.xml b/man/sd_journal_get_catalog.xml index c19eb11b20..86eb659fe5 100644 --- a/man/sd_journal_get_catalog.xml +++ b/man/sd_journal_get_catalog.xml @@ -112,6 +112,15 @@ Notes + 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. + The sd_journal_get_catalog() and sd_journal_get_catalog_for_message_id() interfaces are available as a shared library, which can be diff --git a/man/sd_journal_get_cursor.xml b/man/sd_journal_get_cursor.xml index a400d8b1b5..0a20c36146 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_cursor @@ -122,6 +122,8 @@ Notes + + The sd_journal_get_cursor() and sd_journal_test_cursor() interfaces are available as a shared library, which can be compiled and linked to diff --git a/man/sd_journal_get_cutoff_realtime_usec.xml b/man/sd_journal_get_cutoff_realtime_usec.xml index 23e7cc65e8..782228009d 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_cutoff_realtime_usec @@ -120,6 +120,8 @@ Notes + + The sd_journal_get_cutoff_realtime_usec() and sd_journal_get_cutoff_monotonic_usec() diff --git a/man/sd_journal_get_data.xml b/man/sd_journal_get_data.xml index 1afbd7371c..dce421795a 100644 --- a/man/sd_journal_get_data.xml +++ b/man/sd_journal_get_data.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_data @@ -183,6 +183,8 @@ Notes + + The sd_journal_get_data(), sd_journal_enumerate_data(), sd_journal_restart_data(), diff --git a/man/sd_journal_get_fd.xml b/man/sd_journal_get_fd.xml index 3a38f733ab..a96857d0df 100644 --- a/man/sd_journal_get_fd.xml +++ b/man/sd_journal_get_fd.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_fd @@ -231,6 +231,8 @@ else { Notes + + The sd_journal_get_fd(), sd_journal_get_events(), sd_journal_reliable_fd(), diff --git a/man/sd_journal_get_realtime_usec.xml b/man/sd_journal_get_realtime_usec.xml index 607d74666b..b67e4d6c2d 100644 --- a/man/sd_journal_get_realtime_usec.xml +++ b/man/sd_journal_get_realtime_usec.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_realtime_usec @@ -115,6 +115,8 @@ Notes + + The sd_journal_get_realtime_usec() and sd_journal_get_monotonic_usec() interfaces are available as a shared library, which can be compiled and diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 72c804d834..6281bc850d 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_get_usage @@ -80,6 +80,8 @@ Notes + + The sd_journal_get_usage() interface is available as a shared library, which can be compiled and linked to with the diff --git a/man/sd_journal_has_runtime_files.xml b/man/sd_journal_has_runtime_files.xml index 237e649206..4dff3c67d0 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_has_runtime_files @@ -85,6 +85,12 @@ + + Notes + + + + See Also diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 115fe26661..c8664994ce 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_next @@ -146,6 +146,8 @@ Notes + + The sd_journal_next(), sd_journal_previous(), sd_journal_next_skip() and diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index fb572802a3..c3044670de 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_open @@ -196,6 +196,8 @@ Notes + + The sd_journal_open(), sd_journal_open_directory() and sd_journal_close() interfaces are available diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 0cd0b45b9a..50ad5de7be 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_print @@ -232,6 +232,8 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( Notes + + The sd_journal_print(), sd_journal_printv(), sd_journal_send() and diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index ac0e5f633f..074dfd6789 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_query_unique @@ -145,6 +145,8 @@ Notes + + The sd_journal_query_unique(), sd_journal_enumerate_unique() and sd_journal_restart_unique() interfaces are diff --git a/man/sd_journal_seek_head.xml b/man/sd_journal_seek_head.xml index d74c2d5bbc..8bbbb22a73 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_seek_head @@ -144,6 +144,8 @@ Notes + + The sd_journal_seek_head(), sd_journal_seek_tail(), sd_journal_seek_monotonic_usec(), diff --git a/man/sd_journal_stream_fd.xml b/man/sd_journal_stream_fd.xml index 2ea7731b48..340760ba36 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -21,7 +21,7 @@ along with systemd; If not, see . --> - + sd_journal_stream_fd @@ -104,6 +104,8 @@ Notes + + The sd_journal_stream_fd() interface is available as a shared library, which can be compiled and linked to with the 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. + +