add send function to targets

Author: goatshriek

include/private/target.h

@@ -27,6 +27,28 @@
 void
 destroy_target( const struct stumpless_target *target );
 
+/**
+ * Initializes a given target structure.
+ *
+ * **Thread Safety: MT-Unsafe**
+ * This function is not thread safe, as it initializes the lock that is
+ * otherwise used to coordinate changes
+ *
+ * **Async Signal Safety: AS-Unsafe**
+ * This function is not safe to call from signal handlers due to the
+ * initialization of the lock.
+ *
+ * **Async Cancel Safety: AC-Unsafe**
+ * This function is not safe to call from signal handlers due to the
+ * initialization of the lock.
+ *
+ * @param target The target structure to initialize.
+ *
+ * @return The initialized target, or NULL if an error occurs.
+ */
+struct stumpless_target *
+load_target( struct stumpless_target *target );
+
 void
 lock_target( const struct stumpless_target *target );
 
@@ -89,6 +111,9 @@ target_free_thread( void );
 int
 unchecked_get_option( const struct stumpless_target *target, int option );
 
+void
+unload_target( const struct stumpless_target *target );
+
 void
 unlock_target( const struct stumpless_target *target );
 

include/private/target/buffer.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2018-2020 Joel E. Anderson
+ * Copyright 2018-2025 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,11 +17,11 @@
  */
 
 #ifndef __STUMPLESS_PRIVATE_TARGET_BUFFER_H
-#  define __STUMPLESS_PRIVATE_TARGET_BUFFER_H
+#define __STUMPLESS_PRIVATE_TARGET_BUFFER_H
 
-#  include <stddef.h>
-#  include <stumpless/config.h>
-#  include "private/config/wrapper/thread_safety.h"
+#include <stddef.h>
+#include <stumpless/config.h>
+#include "private/config/wrapper/thread_safety.h"
 
 /**
  * Internal representation of a buffer target.
@@ -30,6 +30,8 @@
  * of the buffer is reached, and writing over older messages.
  */
 struct buffer_target {
+/** The base target structure. */
+  struct stumpless_target target;
 /** The buffer logged messages are written into. */
   char *buffer;
 /** The size of buffer. */
@@ -43,68 +45,13 @@ struct buffer_target {
  * Protects updates to buffer and the position counters. This mutex must be
  * locked by a thread before it can read from or write to the buffer.
  *
- * Size is _not_ protected by this mutex, as it must not change over the life
- * of the buffer target.
+ * The size field is _not_ protected by this mutex, as it must not change over
+ * the life of the buffer target.
  */
   config_mutex_t buffer_mutex;
 #  endif
 };
 
-/**
- * @brief Cleans up and deallocates a buffer target structure.
- *
- * This function is responsible for releasing the resources associated with
- * a `buffer_target` structure. Specifically, it destroys the mutex protecting
- * the buffer and frees the memory occupied by the `buffer_target` instance.
- *
- * **Thread Safety: MT-Unsafe**
- * The caller must ensure that no other threads are accessing the buffer_target 
- * while this function is executed.
- * 
- * **Async Signal Safety: AS-Unsafe*
- * The function destroys a mutex, which is not safe to use in a signal handler context.
- * 
- * **Async Cancel Safety: AC-Unsafe**
- * The function is not safe to call from threads that may be asynchronously canceled.
- * If a thread is canceled while destroying the mutex or freeing memory, it might leave
- * the program in an inconsistent state.
- * 
- * @param target A pointer to the `buffer_target` structure to be destroyed.
- *               Must not be `NULL`.
- */
-void
-destroy_buffer_target( const struct buffer_target *target );
-
-/**
- * @brief Creates and initializes a new buffer target structure.
- *
- * This function allocates memory for a `buffer_target` structure and initializes
- * its fields. The buffer target is designed to manage a pre-allocated buffer
- * with specified size, enabling read and write operations.
- *
- * **Thread Safety: MT-Safe**
- * The function is thread-safe because it initializes a mutex (buffer_mutex)
- * specifically for the buffer_target. This ensures that subsequent operations on
- * the buffer_target can be performed in a thread-safe manner.
- * 
- * **Async Signal Safety: AS-Unsafe*
- * It uses dynamic memory allocation (e.g., malloc or similar), which is not signal-safe. 
- * 
- * **Async Cancel Safety: AC-Unsafe**
- * The function is not safe to call from threads that may be asynchronously canceled
- * because the memory allocation (or its failure) might not handle thread cancellation properly
- * 
- * @param buffer A pointer to the pre-allocated memory buffer that this target
- *               will manage. This buffer must be valid for the lifetime of the
- *               `buffer_target` structure.
- * @param size The size of the buffer in bytes.
- *
- * @return A pointer to the newly allocated and initialized `buffer_target`
- *         structure, or `NULL` if memory allocation fails.
- */
-struct buffer_target *
-new_buffer_target( char *buffer, size_t size );
-
 /**
  * @brief Writes a message to a buffer target, wrapping around if needed.
  *

include/stumpless/target.h

@@ -165,6 +165,29 @@ typedef struct stumpless_entry * ( *stumpless_map_func_t )(
   const struct stumpless_entry *entry,
   void *data );
 
+/**
+ * A function that sends an entry to a target.
+ *
+ * The send function is responsible for actually sending the entry to the
+ * target. It does not handle any per-target tasks such as filtering.
+ *
+ * @since release v3.0.0
+ *
+ * @param target The target to send the entry to.
+ *
+ * @param entry The entry to send to the target.
+ *
+ * @data A pointer to data that may hold anything that the logging function
+ * needs to use in addition to the target and entry.
+ *
+ * @return A non-negative number if no error was encountered. Otherwise, a
+ * negative number must be returned.
+ */
+typedef int ( *stumpless_send_func_t )(
+  const struct stumpless_target *target,
+  const struct stumpless_entry *entry,
+  void *data );
+
 /**
  * A target that log entries can be sent to.
  */
@@ -243,6 +266,19 @@ struct stumpless_target {
  * @since release v3.0.0
  */
   void *map_data;
+/**
+ * The function to use to log entries after filtering and mapping. This must
+ * not be NULL.
+ *
+ * @since release v3.0.0
+ */
+  stumpless_send_func_t send;
+/**
+ * A pointer to data which may be used by the send function.
+ *
+ * @since release v3.0.0
+ */
+  void *send_data;
 #ifdef STUMPLESS_THREAD_SAFETY_SUPPORTED
 /**
  * A pointer to a mutex which protects all target fields. The exact type of

include/stumpless/target/buffer.h

@@ -41,15 +41,36 @@
  */
 
 #ifndef __STUMPLESS_TARGET_BUFFER_H
-#  define __STUMPLESS_TARGET_BUFFER_H
+#define __STUMPLESS_TARGET_BUFFER_H
 
-#  include <stddef.h>
-#  include <stumpless/config.h>
-#  include <stumpless/target.h>
+#include <stddef.h>
+#include <stumpless/config.h>
+#include <stumpless/target.h>
 
-#  ifdef __cplusplus
+#ifdef __cplusplus
 extern "C" {
-#  endif
+#endif
+
+/**
+ * Sends an entry to a buffer target.
+ *
+ * @since release v3.0.0
+ *
+ * @param target The target to send the entry to.
+ *
+ * @param entry The entry to send to the target.
+ *
+ * @data A pointer to data that may hold anything that the logging function
+ * needs to use in addition to the target and entry.
+ *
+ * @return A non-negative number if no error was encountered. Otherwise, a
+ * negative number must be returned.
+ */
+STUMPLESS_PUBLIC_FUNCTION
+int
+stumpless_buffer_send( const struct stumpless_target *target,
+                       const struct stumpless_entry *entry,
+                       void *data );
 
 /**
  * Closes a buffer target.
@@ -161,7 +182,7 @@ stumpless_read_buffer( struct stumpless_target *target,
                        char *buffer,
                        size_t max_length );
 
-#  ifdef __cplusplus
+#ifdef __cplusplus
 }                               /* extern "C" */
-#  endif
+#endif
 #endif                          /* __STUMPLESS_TARGET_BUFFER_H */

src/target.c

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /*
- * Copyright 2018-2024 Joel E. Anderson
+ * Copyright 2018-2025 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -31,7 +31,6 @@
 #include <stumpless/param.h>
 #include <stumpless/severity.h>
 #include <stumpless/target.h>
-#include <stumpless/error.h>
 #include <stumpless/target/buffer.h>
 #include <stumpless/target/file.h>
 #include <stumpless/target/function.h>
@@ -259,7 +258,8 @@ stumpless_add_entry( struct stumpless_target *target,
   switch ( target->type ) {
 
     case STUMPLESS_BUFFER_TARGET:
-      result = sendto_buffer_target( target->id, buffer, builder_length );
+      //result = sendto_buffer_target( ( struct buffer_target * ) target, buffer, builder_length );
+      result = target->send( target, entry, target->send_data );
       break;
 
     case STUMPLESS_FILE_TARGET:
@@ -1147,13 +1147,35 @@ vstumpless_trace_message( struct stumpless_target *target,
 
 void
 destroy_target( const struct stumpless_target *target ) {
-  config_compare_exchange_ptr( &current_target, target, NULL );
-
-  config_destroy_cached_mutex( target->mutex );
+  unload_target( target );
   free_mem( target->name );
   free_mem( target );
 }
 
+struct stumpless_target *
+load_target( struct stumpless_target *target ){
+  config_assign_cached_mutex( target->mutex );
+  if( !config_check_mutex_valid( target->mutex ) ) {
+    return NULL;
+  }
+
+  target->options = stumpless_get_default_options();
+  target->default_prival = get_prival( STUMPLESS_DEFAULT_FACILITY,
+                                       STUMPLESS_DEFAULT_SEVERITY );
+  target->default_app_name[0] = '-';
+  target->default_app_name_length = 1;
+  target->default_msgid[0] = '-';
+  target->default_msgid_length = 1;
+  target->mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_DEBUG_VALUE );
+  target->filter = stumpless_mask_filter;
+  target->filter_data = NULL;
+  target->map = NULL;
+  target->map_data = NULL;
+  target->send_data = NULL;
+
+  return target;
+}
+
 void
 lock_target( const struct stumpless_target *target ) {
   config_lock_mutex( target->mutex );
@@ -1177,29 +1199,14 @@ new_target( enum stumpless_target_type type, const char *name ) {
     target->name = NULL;
   }
 
-  config_assign_cached_mutex( target->mutex );
-  if( !config_check_mutex_valid( target->mutex ) ) {
-    goto fail_mutex;
+  if( !load_target( target ) ){
+    goto fail_load;
   }
-
-  target->id = NULL;
   target->type = type;
-  target->options = stumpless_get_default_options();
-  target->default_prival = get_prival( STUMPLESS_DEFAULT_FACILITY,
-                                       STUMPLESS_DEFAULT_SEVERITY );
-  target->default_app_name[0] = '-';
-  target->default_app_name_length = 1;
-  target->default_msgid[0] = '-';
-  target->default_msgid_length = 1;
-  target->mask = STUMPLESS_SEVERITY_MASK_UPTO( STUMPLESS_SEVERITY_DEBUG_VALUE );
-  target->filter = stumpless_mask_filter;
-  target->filter_data = NULL;
-  target->map = NULL;
-  target->map_data = NULL;
 
   return target;
 
-fail_mutex:
+fail_load:
   free_mem( target->name );
   target->name = NULL;
 fail_name:
@@ -1277,6 +1284,12 @@ target_free_thread( void ) {
   }
 }
 
+void
+unload_target( const struct stumpless_target *target ){
+  config_compare_exchange_ptr( &current_target, target, NULL );
+  config_destroy_cached_mutex( target->mutex );
+}
+
 void
 unlock_target( const struct stumpless_target *target ) {
   config_unlock_mutex( target->mutex );