From 92284c8427ff25656ac235238de75b30353c88e4 Mon Sep 17 00:00:00 2001 From: vboxuser Date: Thu, 2 Nov 2023 15:27:14 +0300 Subject: [PATCH 1/4] Documentation of first 3 functions in entry.h --- include/private/entry.h | 114 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/include/private/entry.h b/include/private/entry.h index f4b0d1ab3..107997264 100644 --- a/include/private/entry.h +++ b/include/private/entry.h @@ -27,24 +27,138 @@ # include # include "private/strbuilder.h" +/** + * Frees entry cache + * + * **Thread Safety: MT-Unsafe** + * This function is not thread safe as it destroys resources(entry cache) that other + * threads can use. + * + * **Async Signal Safety: AS-Unsafe** + * This function is not safe to call from signal handlers due to destroying resources + * (entry cache) that might be used within a function. + * + * **Async Cancel Safety: AC-Unsafe** + * This function is not safe to call from threads that may be asynchronously + * cancelled, due to leaving memory in an undefined state. + * + * @since release v1.6.0 + * + */ void entry_free_all( void ); +/** + * Gets the priority value from facility and severity parameters. + * + * Priority value is calculated by left shifting the facility value by 3 + * and adding it to the severity value which is according to the + * RFC 5424 Section 6.2.1. The shift operation is done prior to get_prival() + * function with macros in "facility.h" + * + * **Thread Safety: MT-Safe** + * This function is thread safe. + * + * **Async Signal Safety: AS-Safe ** + * This function must be safe to call from signal handlers + * + * **Async Cancel Safety: AC-Safe** + * This function must be safe to call from threads that may be asynchronously + * cancelled. + * + * @since release v2.0.0 + * + * @param facility Facility value. This should be a \c STUMPLESS_FACILITY value. + * + * @param severity Severity value. This should be a \c STUMPLESS_SEVERITY value + * + * @return Priority value + */ int get_prival( enum stumpless_facility facility, enum stumpless_severity severity ); +/** + * Locks the mutex within the entry so that no other thread can acces specified entry. + * + * **Thread Safety: MT-Safe** + * This function is thread safe. + * + * **Async Signal Safety: AS-Unsafe ** + * This function is not safe to call from signal handlers due to the use of + * function 'pthread_mutex_lock()' from that is not guarenteed to + * be async signal safe. + * + * **Async Cancel Safety: AC-Unsafe** + * This function is not safe to call from threads that may be asynchronously + * cancelled, due to the use of lock that could be left in undefined state. + * + * @since release v2.0.0 + * + * @param entry The entry to be locked. + * + */ void lock_entry( const struct stumpless_entry *entry ); +/**< + * Adds the element to the entry. + * + * **Thread Safety: MT-Unsafe** + * This function is not thread safe as it doesn't use any synchronization or locking + * mechanisms while accessing shared resources. + * + * **Async Signal Safety: AS-Unsafe lock heap** + * This function is not safe to call from signal handlers due to the use of a + * non-reentrant lock to coordinate access and the use of memory management + * functions to create the new param. + * + * **Async Cancel Safety: AC-Unsafe lock heap** + * This function is not safe to call from threads that may be asynchronously + * cancelled, due to the use of a lock that could be left locked as well as + * memory management functions. + * + * @since release v1.6.0 + * + * @param entry The entry to add the new element to. + * + * @param element The new element to add to entry. + * + * @return The modified entry if no error is encountered. If an error is + * encountered NULL is returned. + */ struct stumpless_entry * locked_add_element( struct stumpless_entry *entry, struct stumpless_element *element ); +/**< + * Returns the element located at index within the entry. + * + * **Thread Safety: MT-Safe race:param_name race:param_value** + * < + * + * **Async Signal Safety: AS-Unsafe lock heap** + * <m. + * + * **Async Cancel Safety: AC-Unsafe lock heap** + * < + * + * @since release v1.6.0 + * + * @param element The element to add the new param to. + * + * @param param_name The name of the new param. + * + * @param param_value The value of the new param. + * + * @return The modified element if no error is encountered. If an error is + * encountered, then NULL is returned and an error code is set appropriately. + */ struct stumpless_element * locked_get_element_by_index( const struct stumpless_entry *entry, size_t index ); + struct stumpless_element * locked_get_element_by_name( const struct stumpless_entry *entry, const char *name ); From 162e7620f2aebb30d869ca38c698dbecfdf12967 Mon Sep 17 00:00:00 2001 From: vboxuser Date: Thu, 2 Nov 2023 16:56:38 +0300 Subject: [PATCH 2/4] First 5 functions are documented --- include/private/entry.h | 59 ++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/include/private/entry.h b/include/private/entry.h index 107997264..e2eec675b 100644 --- a/include/private/entry.h +++ b/include/private/entry.h @@ -31,12 +31,12 @@ * Frees entry cache * * **Thread Safety: MT-Unsafe** - * This function is not thread safe as it destroys resources(entry cache) that other - * threads can use. + * This function is not thread safe as it destroys resources(entry cache) + * that other threads can use. * * **Async Signal Safety: AS-Unsafe** - * This function is not safe to call from signal handlers due to destroying resources - * (entry cache) that might be used within a function. + * This function is not safe to call from signal handlers due to destroying + * resources(entry cache) that might be used within a function. * * **Async Cancel Safety: AC-Unsafe** * This function is not safe to call from threads that may be asynchronously @@ -79,7 +79,7 @@ get_prival( enum stumpless_facility facility, enum stumpless_severity severity ); /** - * Locks the mutex within the entry so that no other thread can acces specified entry. + * Locks the mutex within the entry. * * **Thread Safety: MT-Safe** * This function is thread safe. @@ -101,26 +101,25 @@ get_prival( enum stumpless_facility facility, void lock_entry( const struct stumpless_entry *entry ); -/**< +/** * Adds the element to the entry. * * **Thread Safety: MT-Unsafe** - * This function is not thread safe as it doesn't use any synchronization or locking - * mechanisms while accessing shared resources. + * This function is not thread safe as it doesn't use any synchronization + * or locking mechanisms while accessing shared resources. * - * **Async Signal Safety: AS-Unsafe lock heap** - * This function is not safe to call from signal handlers due to the use of a - * non-reentrant lock to coordinate access and the use of memory management - * functions to create the new param. + * **Async Signal Safety: AS-Unsafe** + * This function is not safe to call from signal handlers due to the use of + * memory functions. * - * **Async Cancel Safety: AC-Unsafe lock heap** + * **Async Cancel Safety: AC-Unsafe** * This function is not safe to call from threads that may be asynchronously - * cancelled, due to the use of a lock that could be left locked as well as - * memory management functions. + * cancelled, due to the use of memory functions that could leave the + * memory in undefined state. * - * @since release v1.6.0 + * @since release v2.6.0 * - * @param entry The entry to add the new element to. + * @param entry The entry to add the new element. * * @param element The new element to add to entry. * @@ -131,27 +130,27 @@ struct stumpless_entry * locked_add_element( struct stumpless_entry *entry, struct stumpless_element *element ); -/**< +/** * Returns the element located at index within the entry. * - * **Thread Safety: MT-Safe race:param_name race:param_value** - * < - * - * **Async Signal Safety: AS-Unsafe lock heap** - * <m. + * **Thread Safety: MT-Unsafe** + * This function is not thread safe as it doesn't use any synchronization + * or locking mechanisms while accessing shared resources. * - * **Async Cancel Safety: AC-Unsafe lock heap** - * < + * **Async Signal Safety: AS-Safe** + * This function is safe to call from signal handlers. * - * @since release v1.6.0 + * **Async Cancel Safety: AC-Safe** + * This function is safe to call from threads that may be asynchronously + * canceled. * - * @param element The element to add the new param to. + * @since release v2.0.0 * - * @param param_name The name of the new param. + * @param entry The entry to get the element from. * - * @param param_value The value of the new param. + * @param index The index of element within the entry. * - * @return The modified element if no error is encountered. If an error is + * @return The element if no error is encountered. If an error is * encountered, then NULL is returned and an error code is set appropriately. */ struct stumpless_element * From 28d621d917856827666556277fa787f9fbab4944 Mon Sep 17 00:00:00 2001 From: vboxuser Date: Fri, 10 Nov 2023 14:44:53 +0300 Subject: [PATCH 3/4] Documentation fixes for the reviewed changes: shorten confusing parts and fix uncorrent AC-safety documentation --- include/private/entry.h | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/include/private/entry.h b/include/private/entry.h index e2eec675b..c03bfa9b4 100644 --- a/include/private/entry.h +++ b/include/private/entry.h @@ -42,8 +42,6 @@ * This function is not safe to call from threads that may be asynchronously * cancelled, due to leaving memory in an undefined state. * - * @since release v1.6.0 - * */ void entry_free_all( void ); @@ -86,8 +84,7 @@ get_prival( enum stumpless_facility facility, * * **Async Signal Safety: AS-Unsafe ** * This function is not safe to call from signal handlers due to the use of - * function 'pthread_mutex_lock()' from that is not guarenteed to - * be async signal safe. + * mutexes that are not guarenteed to be async signal safe. * * **Async Cancel Safety: AC-Unsafe** * This function is not safe to call from threads that may be asynchronously @@ -137,12 +134,14 @@ locked_add_element( struct stumpless_entry *entry, * This function is not thread safe as it doesn't use any synchronization * or locking mechanisms while accessing shared resources. * - * **Async Signal Safety: AS-Safe** - * This function is safe to call from signal handlers. + * **Async Signal Safety: AS-Unsafe** + * This function is not safe to call from signal handlers due to use of + * thread global structrues. * - * **Async Cancel Safety: AC-Safe** - * This function is safe to call from threads that may be asynchronously - * canceled. + * **Async Cancel Safety: AC-Unsafe** + * This function is not safe to call from threads that may be asynchronously + * canceled due to use of thread-global structure that may left in a + * undefined state when cancelled * * @since release v2.0.0 * @@ -157,7 +156,6 @@ struct stumpless_element * locked_get_element_by_index( const struct stumpless_entry *entry, size_t index ); - struct stumpless_element * locked_get_element_by_name( const struct stumpless_entry *entry, const char *name ); From 7dcf8f01e5675818d8ea6881faeab6f6148a8ec8 Mon Sep 17 00:00:00 2001 From: vboxuser Date: Fri, 10 Nov 2023 20:51:40 +0300 Subject: [PATCH 4/4] since tags removed --- include/private/entry.h | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/include/private/entry.h b/include/private/entry.h index c03bfa9b4..23c83f332 100644 --- a/include/private/entry.h +++ b/include/private/entry.h @@ -64,8 +64,6 @@ entry_free_all( void ); * This function must be safe to call from threads that may be asynchronously * cancelled. * - * @since release v2.0.0 - * * @param facility Facility value. This should be a \c STUMPLESS_FACILITY value. * * @param severity Severity value. This should be a \c STUMPLESS_SEVERITY value @@ -90,8 +88,6 @@ get_prival( enum stumpless_facility facility, * This function is not safe to call from threads that may be asynchronously * cancelled, due to the use of lock that could be left in undefined state. * - * @since release v2.0.0 - * * @param entry The entry to be locked. * */ @@ -114,8 +110,6 @@ lock_entry( const struct stumpless_entry *entry ); * cancelled, due to the use of memory functions that could leave the * memory in undefined state. * - * @since release v2.6.0 - * * @param entry The entry to add the new element. * * @param element The new element to add to entry. @@ -141,9 +135,7 @@ locked_add_element( struct stumpless_entry *entry, * **Async Cancel Safety: AC-Unsafe** * This function is not safe to call from threads that may be asynchronously * canceled due to use of thread-global structure that may left in a - * undefined state when cancelled - * - * @since release v2.0.0 + * undefined state when cancelled. * * @param entry The entry to get the element from. *