verdure_ioc/
lib.rs

1//! Verdure IoC Container - Core IoC Module of the Verdure Ecosystem
2//!
3//! This crate provides the foundational Inversion of Control (IoC) container functionality
4//! for the **Verdure ecosystem framework**. As the core dependency injection engine of Verdure,
5//! it enables the declarative, annotation-driven development model that powers the entire
6//! ecosystem.
7//!
8//! ## Ecosystem Integration
9//!
10//! As a core module of the Verdure ecosystem, this IoC container integrates seamlessly with:
11//!
12//! - **verdure-web**: Web framework components and request handling
13//! - **verdure-data**: Repository and data access layer components  
14//! - **verdure-config**: Configuration-driven component initialization
15//! - **verdure-security**: Authentication and authorization components
16//! - **verdure-boot**: Auto-configuration and component discovery
17//!
18//! ## Core Features
19//!
20//! * **Ecosystem Foundation**: Powers dependency injection across all Verdure modules
21//! * **Annotation-Driven**: `#[derive(Component)]` and `#[autowired]` for declarative configuration
22//! * **Component Lifecycle**: Comprehensive lifecycle management with singleton and prototype scopes
23//! * **Event System**: Container lifecycle events for monitoring and debugging
24//! * **Circular Dependency Detection**: Prevents infinite dependency loops
25//! * **Thread Safety**: Full support for multi-threaded applications
26//! * **Zero-Cost Abstractions**: Compile-time dependency resolution where possible
27//!
28//! # Quick Start
29//!
30//! ```rust
31//! use verdure_ioc::{ComponentContainer, ComponentFactory};
32//! use std::sync::Arc;
33//!
34//! // Create a container
35//! let container = ComponentContainer::new();
36//!
37//! // Register a component manually
38//! #[derive(Debug)]
39//! struct DatabaseService {
40//!     connection_string: String,
41//! }
42//!
43//! let db_service = Arc::new(DatabaseService {
44//!     connection_string: "postgres://localhost:5432/db".to_string(),
45//! });
46//!
47//! container.register_component(db_service);
48//!
49//! // Retrieve the component
50//! let retrieved_service: Option<Arc<DatabaseService>> = container.get_component();
51//! assert!(retrieved_service.is_some());
52//! ```
53
54mod component;
55mod container;
56mod event;
57
58pub use component::{
59    ComponentDefinition, ComponentInitializer, ComponentInstance, ComponentScope,
60    factory::ComponentFactory,
61};
62
63pub use container::ComponentContainer;
64
65pub use event::{
66    ContainerLifecycleEvent, LifecycleEventPublisher, LifecycleListener,
67    LifecycleListenerDefinition,
68};
69
70/// Macro for registering lifecycle event listeners
71///
72/// This macro simplifies the registration of lifecycle event listeners with the container.
73///
74/// # Arguments
75///
76/// * `$name` - A string literal identifying the listener
77/// * `$handler` - A function that handles lifecycle events
78///
79/// # Examples
80///
81/// ```rust
82/// use verdure_ioc::{lifecycle_listener, ContainerLifecycleEvent};
83///
84/// fn my_event_handler(event: &ContainerLifecycleEvent) {
85///     match event {
86///         ContainerLifecycleEvent::InitializationStarted { .. } => {
87///             println!("Container initialization started");
88///         }
89///         _ => {}
90///     }
91/// }
92///
93/// lifecycle_listener!("my_listener", my_event_handler);
94/// ```
95#[macro_export]
96macro_rules! lifecycle_listener {
97    ($name:expr, $handler:expr) => {
98        inventory::submit! {
99            $crate::LifecycleListenerDefinition {
100                name: $name,
101                handler: $handler,
102            }
103        }
104    };
105}
verdure_ioc/lib.rs

verdure_ioc/
lib.rs
