Object System & Memory Management
Relevant source files
The following files were used as context for generating this wiki page:
Rsyslog utilizes a custom Object System implemented in C to provide encapsulation, polymorphism, and structured lifecycle management within its microkernel-like architecture. This system allows the core engine to interact with various components—such as message objects, queues, and plugins—through standardized interfaces while maintaining strict control over memory allocation and deallocation.
The primary purpose of this system is to simulate object-oriented behavior in a procedural language, ensuring that resources like smsg_t (Message Objects) or qqueue_t (Queues) follow a predictable lifecycle of construction, configuration, and destruction. This architectural pattern is essential for maintaining stability in a multi-threaded, high-performance logging environment. Sources: doc/source/development/architecture.rst:11-13, doc/source/development/architecture.rst:64-67
The Object System Architecture
The Object System is the foundation of the rsyslog runtime, providing the infrastructure for defining "classes" and "interfaces" via C macros. It enables the core engine to manage dynamically loadable modules and internal resources without being tightly coupled to their specific implementations.
Lifecycle Management
Every object in the system follows a strict, four-stage lifecycle to ensure memory safety and proper initialization.
- Construct: Allocation of memory for the object instance.
- SetProperty: Configuration of the object's initial state or parameters.
- ConstructFinalize: Validation of the configuration and transitioning the object to a "ready-to-use" state.
- Destruct: Teardown of resources and freeing of allocated memory.
Sources: doc/source/development/architecture.rst:71-77
Implementation via Macros
The system relies heavily on preprocessor macros to define interfaces and instances. Key macros include:
DEFobjCurrIf: Defines the current interface for an object type.BEGINobjInstance: Marks the beginning of an object instance definition.
Sources: doc/source/development/architecture.rst:68-70
Object Lifecycle Flow
The following diagram illustrates the standard sequence for managing an object's life within the rsyslog runtime.
The lifecycle ensures that no object is used before it is fully configured and that all resources are reclaimed upon destruction.
Sources: doc/source/development/architecture.rst:71-77
Memory Management & Worker Model
Rsyslog's memory management is tightly integrated with its v8 worker model, which defines how data is shared or isolated across threads. Memory safety is achieved through a clear distinction between shared "Action" data and thread-local "Worker" data.
Data Isolation Patterns
Memory is categorized based on its scope and the required locking mechanisms:
| Data Type | Implementation Structure | Scope | Locking Requirement |
|---|---|---|---|
| Worker Data | wrkrInstanceData_t (WID) | Per-worker, thread-local | No locks needed (owned by one worker) |
| Action Data | pData | Shared across workers | Must guard mutable/shared members |
| Serial Resources | Streams, Files in pData | Shared/Inherently Serial | Must be serialized using mutexes |
Sources: DEVELOPING.md:4-15
Memory Ownership Rules
- No WID Sharing: A
wrkrInstanceData_tmust never be shared across different workers. - Shared Mutables: Any shared mutable member in
pDatamust be protected by apthread_mutex_torpthread_rwlock_t. - Lifecycle Entry Points: Modules must implement
createWrkrInstanceandfreeWrkrInstanceto handle the allocation and deallocation of thread-local memory.
Sources: DEVELOPING.md:21-27, DEVELOPING.md:42-45
Core Object Examples: The Message Object (smsg_t)
The smsg_t object is a primary example of the object system in action. It represents a single log entry and is passed through the data flow pipeline.
Message Data Flow
The message object is created by an input module and processed by the core engine before being consumed by an output module.
The message object transitions through the system, managed by the core's queueing and object systems.
Sources: doc/source/development/architecture.rst:45-56
Core Engine Components
The Object System is implemented across several key files in the runtime/ directory:
obj.c/obj.h: The internal Object System core and macro definitions.msg.c/msg.h: Implementation of the Message object.queue.c: Implementation of theqqueue_t(Queue) object, supporting memory, disk, and Disk-Assisted (DA) modes.
Sources: doc/source/development/architecture.rst:59-63
Summary of Implementation Logic
Rsyslog's Object System provides a structured way to handle the complexity of a plugin-based architecture in C. By enforcing a strict lifecycle and clear memory ownership rules (WID vs. pData), it minimizes common issues like race conditions and memory leaks. The system allows the Microkernel Core to remain agnostic of specific protocol implementations while maintaining high-performance, event-driven log processing. Sources: doc/source/development/architecture.rst:17-25, DEVELOPING.md:4-10