5454//! }
5555//! ```
5656
57- use std:: fmt:: Debug ;
57+ use std:: { fmt:: Debug , time :: Duration } ;
5858
59+ use iceoryx2_bb_elementary:: enum_gen;
5960use iceoryx2_bb_memory:: bump_allocator:: BumpAllocator ;
6061use iceoryx2_bb_system_types:: file_name:: * ;
62+ use tiny_fn:: tiny_fn;
6163
6264use crate :: static_storage:: file:: { NamedConcept , NamedConceptBuilder , NamedConceptMgmt } ;
6365
66+ tiny_fn ! {
67+ pub ( crate ) struct Initializer <T > = FnMut ( value: & mut T , allocator: & mut BumpAllocator ) -> bool ;
68+ }
69+
70+ impl < T > Debug for Initializer < ' _ , T > {
71+ fn fmt ( & self , f : & mut std:: fmt:: Formatter < ' _ > ) -> std:: fmt:: Result {
72+ write ! ( f, "" )
73+ }
74+ }
75+
6476pub mod posix_shared_memory;
6577pub mod process_local;
6678
6779/// Describes failures when creating a new [`DynamicStorage`]
6880#[ derive( Debug , Clone , Copy , Eq , Hash , PartialEq ) ]
6981pub enum DynamicStorageCreateError {
7082 AlreadyExists ,
71- Creation ,
72- Write ,
83+ InsufficientPermissions ,
7384 InitializationFailed ,
7485 InternalError ,
7586}
@@ -78,13 +89,20 @@ pub enum DynamicStorageCreateError {
7889#[ derive( Debug , Clone , Copy , Eq , Hash , PartialEq ) ]
7990pub enum DynamicStorageOpenError {
8091 DoesNotExist ,
81- Open ,
8292 InitializationNotYetFinalized ,
93+ VersionMismatch ,
8394 InternalError ,
8495}
8596
97+ enum_gen ! {
98+ DynamicStorageOpenOrCreateError
99+ mapping:
100+ DynamicStorageOpenError ,
101+ DynamicStorageCreateError
102+ }
103+
86104/// Builder for the [`DynamicStorage`]. T is not allowed to implement the [`Drop`] trait.
87- pub trait DynamicStorageBuilder < T : Send + Sync , D : DynamicStorage < T > > :
105+ pub trait DynamicStorageBuilder < ' builder , T : Send + Sync , D : DynamicStorage < T > > :
88106 Debug + Sized + NamedConceptBuilder < D >
89107{
90108 /// Defines if a newly created [`DynamicStorage`] owns the underlying resources
@@ -93,37 +111,38 @@ pub trait DynamicStorageBuilder<T: Send + Sync, D: DynamicStorage<T>>:
93111 /// Sets the size of the supplementary data
94112fn supplementary_size ( self , value : usize ) -> Self ;
95113
114+ /// The timeout defines how long the [`DynamicStorageBuilder`] should wait for
115+ /// [`DynamicStorageBuilder::create()`]
116+ /// to finialize the initialization. This is required when the [`DynamicStorage`] is
117+ /// created and initialized concurrently from another process.
118+ /// By default it is set to [`Duration::ZERO`] for no timeout.
119+ fn timeout ( self , value : Duration ) -> Self ;
120+
121+ /// Before the construction is finalized the initializer is called
122+ /// with a mutable reference to the new value and a mutable reference to a bump allocator
123+ /// which provides access to the supplementary memory. If the initialization failed it
124+ /// shall return false, otherwise true.
125+ fn initializer < F : FnMut ( & mut T , & mut BumpAllocator ) -> bool + ' builder > ( self , value : F )
126+ -> Self ;
127+
96128 /// Creates a new [`DynamicStorage`]. The returned object has the ownership of the
97129/// [`DynamicStorage`] and when it goes out of scope the underlying resources shall be
98130/// removed without corrupting already opened [`DynamicStorage`]s.
99- fn create ( self , initial_value : T ) -> Result < D , DynamicStorageCreateError > {
100- self . create_and_initialize ( initial_value, |_, _| true )
101- }
102-
103- /// Creates a new [`DynamicStorage`]. Before the construction is finalized the initializer
104- /// with a mutable reference to the new value and a mutable reference to a bump allocator
105- /// which provides access to the supplementary memory.
106- fn create_and_initialize < F : FnOnce ( & mut T , & mut BumpAllocator ) -> bool > (
107- self ,
108- initial_value : T ,
109- initializer : F ,
110- ) -> Result < D , DynamicStorageCreateError > ;
131+ fn create ( self , initial_value : T ) -> Result < D , DynamicStorageCreateError > ;
111132
112133 /// Opens a [`DynamicStorage`]. The implementation must ensure that a [`DynamicStorage`]
113- /// which is in the midst of creation cannot be opened.
134+ /// which is in the midst of creation cannot be opened. If the [`DynamicStorage`] does not
135+ /// exist or is not initialized it fails.
114136fn open ( self ) -> Result < D , DynamicStorageOpenError > ;
115137
116- /// Opens a [`DynamicStorage`]. The implementation must ensure that a [`DynamicStorage`]
117- /// which is in the midst of creation cannot be opened. In contrast to the counterpart
118- /// [`DynamicStorageBuilder::open()`] it does not print an error message when the channel
119- /// does not exist or is not yet finalized.
120- fn try_open ( self ) -> Result < D , DynamicStorageOpenError > ;
138+ /// Opens the [`DynamicStorage`] if it exists, otherwise it creates it.
139+ fn open_or_create ( self , initial_value : T ) -> Result < D , DynamicStorageOpenOrCreateError > ;
121140}
122141
123142/// Is being built by the [`DynamicStorageBuilder`]. The [`DynamicStorage`] trait shall provide
124143/// inter-process access to a modifyable piece of memory identified by some name.
125144pub trait DynamicStorage < T : Send + Sync > : Sized + Debug + NamedConceptMgmt + NamedConcept {
126- type Builder : DynamicStorageBuilder < T , Self > ;
145+ type Builder < ' builder > : DynamicStorageBuilder < ' builder , T , Self > ;
127146
128147 /// Returns if the dynamic storage supports persistency, meaning that the underlying OS
129148/// resource remain even when every dynamic storage instance in every process was removed.
0 commit comments