From a8d46a1663c80e96508ed9bbd7c3acd55c5b4252 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Sat, 15 Oct 2016 15:24:55 -0400 Subject: man: add notes about thread safety of sd_journal_* functions Fixes #4056. --- man/sd-journal.xml | 15 +++++++++++++++ man/sd_journal_add_match.xml | 3 +++ man/sd_journal_enumerate_fields.xml | 3 +++ man/sd_journal_get_catalog.xml | 4 ++++ man/sd_journal_get_cursor.xml | 3 +++ man/sd_journal_get_cutoff_realtime_usec.xml | 3 +++ man/sd_journal_get_usage.xml | 3 +++ man/sd_journal_has_runtime_files.xml | 12 ++++++++++++ man/sd_journal_next.xml | 3 +++ man/sd_journal_open.xml | 3 +++ man/sd_journal_print.xml | 7 ++++--- man/sd_journal_query_unique.xml | 3 +++ man/sd_journal_seek_head.xml | 3 +++ man/sd_journal_stream_fd.xml | 4 ++++ 14 files changed, 66 insertions(+), 3 deletions(-) (limited to 'man') diff --git a/man/sd-journal.xml b/man/sd-journal.xml index 936a83acf7..0f4b3e8eea 100644 --- a/man/sd-journal.xml +++ b/man/sd-journal.xml @@ -98,6 +98,21 @@ tool. + + 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 + sd_journal_get_catalog_for_message_id3 + — are thread-safe and may be called from multiple threads in parallel. + + diff --git a/man/sd_journal_add_match.xml b/man/sd_journal_add_match.xml index 98415d53fd..7c64329aed 100644 --- a/man/sd_journal_add_match.xml +++ b/man/sd_journal_add_match.xml @@ -168,6 +168,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_add_match(), sd_journal_add_disjunction(), sd_journal_add_conjunction() and diff --git a/man/sd_journal_enumerate_fields.xml b/man/sd_journal_enumerate_fields.xml index fa5884106b..bc2c21ed4b 100644 --- a/man/sd_journal_enumerate_fields.xml +++ b/man/sd_journal_enumerate_fields.xml @@ -110,6 +110,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_enumerate_fields() and sd_journal_restart_fields() interfaces are available as a shared library, which can be compiled and linked to with the libsystemd  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. + 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..b7aa05f8b2 100644 --- a/man/sd_journal_get_cursor.xml +++ b/man/sd_journal_get_cursor.xml @@ -122,6 +122,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_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..0950e11b44 100644 --- a/man/sd_journal_get_cutoff_realtime_usec.xml +++ b/man/sd_journal_get_cutoff_realtime_usec.xml @@ -120,6 +120,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_get_cutoff_realtime_usec() and sd_journal_get_cutoff_monotonic_usec() diff --git a/man/sd_journal_get_usage.xml b/man/sd_journal_get_usage.xml index 72c804d834..06b0ff534d 100644 --- a/man/sd_journal_get_usage.xml +++ b/man/sd_journal_get_usage.xml @@ -80,6 +80,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_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..3f6d56ca77 100644 --- a/man/sd_journal_has_runtime_files.xml +++ b/man/sd_journal_has_runtime_files.xml @@ -85,6 +85,18 @@ + + Notes + + All functions listed here are thread-agnostic and only a single thread may operate + on a given sd_journal object. + + Functions listed here are available as a shared library, which can be compiled and linked + to with the libsystemd pkg-config1 + file. + + See Also diff --git a/man/sd_journal_next.xml b/man/sd_journal_next.xml index 115fe26661..7c385de260 100644 --- a/man/sd_journal_next.xml +++ b/man/sd_journal_next.xml @@ -146,6 +146,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_next(), sd_journal_previous(), sd_journal_next_skip() and diff --git a/man/sd_journal_open.xml b/man/sd_journal_open.xml index 74e67023b5..25b3048f2e 100644 --- a/man/sd_journal_open.xml +++ b/man/sd_journal_open.xml @@ -208,6 +208,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 diff --git a/man/sd_journal_print.xml b/man/sd_journal_print.xml index 76542527fc..2d8dd635aa 100644 --- a/man/sd_journal_print.xml +++ b/man/sd_journal_print.xml @@ -201,9 +201,10 @@ sd_journal_send("MESSAGE=Hello World, this is PID %lu!", (unsigned long) getpid( - Async signal safety - sd_journal_sendv() is "async signal - safe" in the meaning of + 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 signal7. diff --git a/man/sd_journal_query_unique.xml b/man/sd_journal_query_unique.xml index dbff55c105..d7a41a039c 100644 --- a/man/sd_journal_query_unique.xml +++ b/man/sd_journal_query_unique.xml @@ -150,6 +150,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_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..985073496c 100644 --- a/man/sd_journal_seek_head.xml +++ b/man/sd_journal_seek_head.xml @@ -144,6 +144,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_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..226298ae1b 100644 --- a/man/sd_journal_stream_fd.xml +++ b/man/sd_journal_stream_fd.xml @@ -104,6 +104,10 @@ Notes + Function sd_journal_stream_fd() is thread-safe and may be be called + from multiple threads. All calls will return the same file descriptor, although temporarily + multiple file descriptors may be open. + The sd_journal_stream_fd() interface is available as a shared library, which can be compiled and linked to with the -- cgit v1.2.3-54-g00ecf