iceoryx2_cal/static_storage/
mod.rs

1// Copyright (c) 2023 Contributors to the Eclipse Foundation
2//
3// See the NOTICE file(s) distributed with this work for additional
4// information regarding copyright ownership.
5//
6// This program and the accompanying materials are made available under the
7// terms of the Apache Software License 2.0 which is available at
8// https://www.apache.org/licenses/LICENSE-2.0, or the MIT license
9// which is available at https://opensource.org/licenses/MIT.
10//
11// SPDX-License-Identifier: Apache-2.0 OR MIT
12
13//! Traits that provide read-only memory which can be accessed by multiple processes
14//! identified by a name.
15
16pub mod file;
17pub mod process_local;
18pub mod recommended;
19
20use core::{fmt::Debug, time::Duration};
21
22use iceoryx2_bb_elementary_traits::testing::abandonable::Abandonable;
23use iceoryx2_bb_system_types::file_name::*;
24use iceoryx2_log::fail;
25
26use crate::named_concept::{
27    NamedConcept, NamedConceptBuilder, NamedConceptConfiguration, NamedConceptMgmt,
28};
29
30#[derive(Debug, Clone, Copy, Eq, Hash, PartialEq)]
31pub enum StaticStorageCreateError {
32    AlreadyExists,
33    Creation,
34    Write,
35    InsufficientPermissions,
36    InternalError,
37}
38
39impl core::fmt::Display for StaticStorageCreateError {
40    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
41        write!(f, "StaticStorageCreateError::{self:?}")
42    }
43}
44
45impl core::error::Error for StaticStorageCreateError {}
46
47#[derive(Debug, Clone, Copy, Eq, Hash, PartialEq)]
48pub enum StaticStorageOpenError {
49    DoesNotExist,
50    Read,
51    InitializationNotYetFinalized,
52    InternalError,
53}
54
55impl core::fmt::Display for StaticStorageOpenError {
56    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
57        write!(f, "StaticStorageOpenError::{self:?}")
58    }
59}
60
61impl core::error::Error for StaticStorageOpenError {}
62
63#[derive(Debug, Clone, Copy, Eq, Hash, PartialEq)]
64pub enum StaticStorageReadError {
65    BufferTooSmall,
66    ReadError,
67    StaticStorageWasModified,
68    CreationNotComplete,
69}
70
71impl core::fmt::Display for StaticStorageReadError {
72    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
73        write!(f, "StaticStorageReadError::{self:?}")
74    }
75}
76
77impl core::error::Error for StaticStorageReadError {}
78
79#[derive(Debug, Clone, Copy, Eq, Hash, PartialEq)]
80pub enum StaticStorageUnlockError {
81    InsufficientPermissions,
82    NoSpaceLeft,
83    InternalError,
84}
85
86impl core::fmt::Display for StaticStorageUnlockError {
87    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
88        write!(f, "StaticStorageUnlockError::{self:?}")
89    }
90}
91
92impl core::error::Error for StaticStorageUnlockError {}
93
94/// A custom configuration which can be used by the [`StaticStorageBuilder`] to create a
95/// [`StaticStorage`] with implementation specific settings.
96pub trait StaticStorageConfiguration: Clone + Default + NamedConceptConfiguration {}
97
98/// Creates either a [`StaticStorage`], that can own the [`StaticStorage`] if it was created with
99/// [`StaticStorageBuilder::has_ownership()`] (default = true) or a [`StaticStorageLocked`] that is
100/// not yet set.
101pub trait StaticStorageBuilder<T: StaticStorage>: Sized + NamedConceptBuilder<T> {
102    /// Defines if a newly created [`StaticStorage`] owns the underlying resources
103    fn has_ownership(self, value: bool) -> Self;
104
105    /// Creates an owning [`StaticStorage`]. When its lifetime ends the underlying resources will
106    /// be removed.
107    fn create(self, contents: &[u8]) -> Result<T, StaticStorageCreateError> {
108        let locked_storage = self.create_locked()?;
109
110        Ok(
111            fail!(from "StaticStorageBuilder::create", when locked_storage.unlock(contents),
112            with StaticStorageCreateError::Write,
113            "Unable to unlock static storage with content"),
114        )
115    }
116
117    /// Creates an owning [`StaticStorageLocked`]. When its lifetime ends the underlying resource
118    /// will be removed. The contents must be set later with [`StaticStorageLocked::unlock()`].
119    /// This is useful if the static storage name should be reserved and initialized later.
120    fn create_locked(self) -> Result<T::Locked, StaticStorageCreateError>;
121
122    /// Opens an already existing [`StaticStorage`]. If the creation of the [`StaticStorage`] is
123    /// not finalized it shall return an error.
124    /// The provided defines how long the [`StaticStorageBuilder`]
125    /// shall wait for [`StaticStorageBuilder::create_locked()`]
126    /// to finalize the initialization and unlock the storage.
127    fn open(self, timeout: Duration) -> Result<T, StaticStorageOpenError>;
128}
129
130/// A locked (uninitialized) static storage which is present but without content
131pub trait StaticStorageLocked<T: StaticStorage>: Sized + NamedConcept + Abandonable {
132    /// Unlocks the static storage by writing the contents to it
133    fn unlock(self, contents: &[u8]) -> Result<T, StaticStorageUnlockError>;
134}
135
136/// A static storage which owns its underlying resources. When it goes out of scope those resources
137/// shall be removed.
138pub trait StaticStorage:
139    Debug + Sized + NamedConceptMgmt + NamedConcept + Send + Sync + Abandonable
140{
141    type Builder: StaticStorageBuilder<Self> + NamedConceptBuilder<Self>;
142    type Locked: StaticStorageLocked<Self>;
143
144    /// Returns the length of the content. Required to provide a buffer in
145    /// [`StaticStorage::read()`] which is large enough.
146    fn len(&self) -> u64;
147
148    /// Returns true if it does not contain any content, otherwise false.
149    fn is_empty(&self) -> bool;
150
151    /// Writes the contents of the [`StaticStorage`] into the provided content buffer. If the
152    /// buffer is too small an error must be returned.
153    fn read(&self, content: &mut [u8]) -> Result<(), StaticStorageReadError>;
154
155    /// Releases the ownership of the static storage. When the object goes out of scope the
156    /// static storage is no longer removed.
157    fn release_ownership(&self);
158
159    /// Acquires the ownership of the static storage. If the object goes out of scope the
160    /// underlying resources are removed.
161    fn acquire_ownership(&self);
162
163    /// The default suffix of every static storage
164    fn default_suffix() -> FileName {
165        unsafe { FileName::new_unchecked(b".static_storage") }
166    }
167}
iceoryx2_cal/static_storage/mod.rs

iceoryx2_cal/static_storage/
mod.rs
