iceoryx2_bb_elementary_traits/
relocatable_container.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//! Describes a container which can shared between processes.
14
15use crate::{allocator::AllocationError, allocator::BaseAllocator};
16
17/// Describes a container which can shared between processes. Since the shared memory is often
18/// mapped at a different virtual memory position the underlying constructs must be relocatable in
19/// the sense that they should not rely on absolut memory positions.
20pub trait RelocatableContainer {
21    /// Creates a new uninitialized RelocatableContainer. Before the container can be used the method
22    /// [`RelocatableContainer::init()`] must be called.
23    ///
24    /// # Safety
25    ///
26    ///  * Before the container can be used [`RelocatableContainer::init()`] must be called exactly
27    ///    once.
28    ///
29    unsafe fn new_uninit(capacity: usize) -> Self;
30
31    /// Initializes an uninitialized RelocatableContainer. It allocates the required memory from
32    /// the provided allocator. The allocator must have at least
33    /// [`RelocatableContainer::memory_size()`] bytes available.
34    ///
35    /// # Safety
36    ///
37    ///  * Must be called exactly once before any other method is called.
38    ///  * Shall be only used when the [`RelocatableContainer`] was created with
39    ///    [`RelocatableContainer::new_uninit()`]
40    ///
41    unsafe fn init<T: BaseAllocator>(&mut self, allocator: &T) -> Result<(), AllocationError>;
42
43    /// Returns the amount of additional memory the object requires from the
44    /// [`BaseAllocator`] in the [`RelocatableContainer::init()`] call. The returned value
45    /// considers the alignment overhead. When implementing this, please use
46    /// `iceoryx2_bb_elementary::math::unaligned_mem_size()`.
47    /// The whole memory consumption is
48    /// `core::mem::size_of::<RelocatableContainer>() + RelocatableContainer::memory_size()`.
49    fn memory_size(capacity: usize) -> usize;
50}
iceoryx2_bb_elementary_traits/relocatable_container.rs

iceoryx2_bb_elementary_traits/
relocatable_container.rs
