diff --git a/include/private/entry.h b/include/private/entry.h index f4b0d1ab3..23c83f332 100644 --- a/include/private/entry.h +++ b/include/private/entry.h @@ -27,20 +27,123 @@ # 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. + * + */ 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. + * + * @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. + * + * **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 + * 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 + * cancelled, due to the use of lock that could be left in undefined state. + * + * @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** + * This function is not safe to call from signal handlers due to the use of + * memory functions. + * + * **Async Cancel Safety: AC-Unsafe** + * This function is not safe to call from threads that may be asynchronously + * cancelled, due to the use of memory functions that could leave the + * memory in undefined state. + * + * @param entry The entry to add the new element. + * + * @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-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** + * This function is not safe to call from signal handlers due to use of + * thread global structrues. + * + * **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. + * + * @param entry The entry to get the element from. + * + * @param index The index of element within the entry. + * + * @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 * locked_get_element_by_index( const struct stumpless_entry *entry, size_t index );