stumpless

Stumpless follows specific naming patterns for object lifecycle management. Ensure you pair constructors with their corresponding destructors:

Dynamic Allocation (Heap)

• new (Constructors): Functions like stumpless_new_entry allocate memory for a new structure and return it.
• destroy (Destructors): Use these to deallocate memory for structures created with new (e.g., stumpless_destroy_entry_and_contents).

Static/Provided Allocation

• load (Constructors): Functions like stumpless_load_entry populate a structure provided as a parameter rather than allocating one. This is often faster due to fewer dynamic allocations.
• unload (Destructors): Use these to clean up structures initialized via load (e.g., stumpless_unload_entry).

State-based Initialization

• open (Constructors): Similar to new, but also transitions the object to an "opened" state. This is currently primarily used for network targets to manage connection states.

Stumpless uses a centralized error handling framework.

Defining Errors

All possible errors are defined in stumpless/error.h within the STUMPLESS_FOREACH_ERROR macro. To add a new error, append it to this list; it will be assigned the next available integer ID.

Raising Errors

Each error has an internal raise function (declared in include/private/error.h and defined in src/error.c). When an operation fails, call the appropriate raise_<error_name> function. These functions set the error ID and localized messages.

Pattern: If a function detects a failure from an internal function that already raises an error (like alloc_mem), simply return without raising a new error to avoid overwriting the original context.

Clearing Errors

Public functions must clear the error state if they succeed so users can distinguish between success and failure. Use clear_error before returning on the non-error path. Destructors and error-handling functions do not need to call this.

Consuming Errors

Users can check for and retrieve errors using:

• stumpless_has_error: Returns true if the last call failed.
• stumpless_get_error: Retrieves the current error struct.
• stumpless_perror: Prints the current error.

Function targets allow you to inject custom logic into the stumpless workflow. Instead of logging to a standard output or file, you can provide a callback function that is executed every time an entry is added to that target. This is useful for real-time data processing, such as incrementing counters, filtering events, or transforming data based on specific criteria.

To implement a function target, you must:

1. Define a callback function with the signature int func(const struct stumpless_target *target, const struct stumpless_entry *entry).
2. Register the function using stumpless_open_function_target.
3. Send entries to the target using stumpless_add_entry.

/* 1. Define the callback */
int my_custom_logic(const struct stumpless_target *target, const struct stumpless_entry *entry) {
  // Custom logic here
  return 0;
}

/* 2. Open the target */
target = stumpless_open_function_target("my-target-name", my_custom_logic);

/* 3. Use the target */
stumpless_add_entry(target, entry);

For logic more complex than severity masking (e.g., filtering based on entry content), you can define a custom filter function and apply it to a target using stumpless_set_filter.

A filter function must match the signature: bool function_name(const struct stumpless_target *target, const struct stumpless_entry *entry).

Note: When you set a custom filter, it replaces the default mask-based filter. If you want to keep the severity mask behavior alongside your custom logic, you must explicitly call stumpless_mask_filter(target, entry) within your custom function.

// 1. Define a filter function
bool
ignore_element_filter( const struct stumpless_target *target, 
                       const struct stumpless_entry *entry ) {
  // Example: filter out entries that contain an element named "ignore"
  return !stumpless_get_element_by_name( entry, "ignore" );
}

// 2. Apply the filter to a target
stumpless_set_filter( target, ignore_element_filter );

// 3. To combine custom logic with the default mask filtering:
bool
combined_filter( const struct stumpless_target *target, 
                 const struct stumpless_entry *entry ) {
  return !stumpless_get_element_by_name( entry, "ignore" )
           && stumpless_mask_filter( target, entry );
}