Reorg SHM examples

commons/zenoh-shm/src/api/protocol_implementations/posix/posix_shm_client.rs

@@ -26,7 +26,7 @@ use crate::api::{
     protocol_implementations::posix::protocol_id::POSIX_PROTOCOL_ID,
 };
 
-/// Client factory implementation for particular shared memory protocol
+/// Client factory implementation for POSIX Shared Memory protocol
 #[zenoh_macros::unstable_doc]
 #[derive(Debug)]
 pub struct PosixShmClient;

commons/zenoh-shm/src/api/protocol_implementations/posix/posix_shm_provider_backend_buddy.rs

@@ -110,16 +110,9 @@ impl ShmProviderBackend for PosixShmProviderBackendBuddy {
     fn alloc(&self, layout: &MemoryLayout) -> ChunkAllocResult {
         tracing::trace!("PosixShmProviderBackendBuddy::alloc({:?})", layout);
 
-        let alloc_layout = unsafe {
-            Layout::from_size_align_unchecked(
-                layout.size().get(),
-                layout.alignment().get_alignment_value().get(),
-            )
-        };
-
         let alloc = {
             let mut lock = zlock!(self.heap);
-            lock.alloc(alloc_layout)
+            lock.alloc(layout.into())
         };
 
         match alloc {

commons/zenoh-shm/src/api/protocol_implementations/posix/posix_shm_provider_backend_talc.rs

@@ -113,16 +113,9 @@ impl ShmProviderBackend for PosixShmProviderBackendTalc {
     fn alloc(&self, layout: &MemoryLayout) -> ChunkAllocResult {
         tracing::trace!("PosixShmProviderBackendTalc::alloc({:?})", layout);
 
-        let alloc_layout = unsafe {
-            Layout::from_size_align_unchecked(
-                layout.size().get(),
-                layout.alignment().get_alignment_value().get(),
-            )
-        };
-
         let alloc = {
             let mut lock = zlock!(self.talc);
-            unsafe { lock.malloc(alloc_layout) }
+            unsafe { lock.malloc(layout.into()) }
         };
 
         match alloc {

commons/zenoh-shm/src/api/protocol_implementations/posix/protocol_id.rs

@@ -14,6 +14,6 @@
 
 use crate::api::common::types::ProtocolID;
 
-/// Protocol identifier to use when creating ShmProvider
+/// Protocol identifier to use for POSIX Protocol
 #[zenoh_macros::unstable_doc]
 pub const POSIX_PROTOCOL_ID: ProtocolID = 0;

commons/zenoh-shm/src/api/provider/memory_layout.rs

@@ -24,6 +24,18 @@ pub struct MemoryLayout {
     alignment: AllocAlignment,
 }
 
+impl From<&MemoryLayout> for core::alloc::Layout {
+    fn from(value: &MemoryLayout) -> Self {
+        // SAFERY: this is safe because `MemoryLayout`'s size and alignment are already checked
+        unsafe {
+            core::alloc::Layout::from_size_align_unchecked(
+                value.size().get(),
+                value.alignment().get_alignment_value().get(),
+            )
+        }
+    }
+}
+
 impl From<&MemoryLayout> for MemoryLayout {
     fn from(other: &MemoryLayout) -> Self {
         *other

examples/Cargo.toml

@@ -28,19 +28,22 @@ publish = false
 
 [features]
 default = ["zenoh-ext/default", "zenoh/default"]
-shared-memory = ["zenoh/shared-memory"]
+shared-memory = ["talc", "zenoh-result", "zenoh-shm", "zenoh/shared-memory"]
 unstable = ["zenoh/unstable"]
 
 [dependencies]
 clap = { workspace = true, features = ["derive"] }
 futures = { workspace = true }
 prost = { workspace = true }
 serde_json = { workspace = true }
+talc = { workspace = true, optional = true }
 tokio = { workspace = true, features = ["io-std", "rt-multi-thread", "time"] }
 zenoh = { workspace = true, default-features = false }
 zenoh-ext = { workspace = true, default-features = false, features = [
   "unstable",
 ] }
+zenoh-result = { workspace = true, optional = true }
+zenoh-shm = { workspace = true, optional = true }
 
 [dev-dependencies]
 rand = { workspace = true, features = ["default"] }
@@ -79,7 +82,7 @@ path = "examples/z_pub.rs"
 
 [[example]]
 name = "z_pub_shm"
-path = "examples/z_pub_shm.rs"
+path = "examples/shm/z_pub_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -88,7 +91,7 @@ path = "examples/z_sub.rs"
 
 [[example]]
 name = "z_sub_shm"
-path = "examples/z_sub_shm.rs"
+path = "examples/shm/z_sub_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -105,7 +108,7 @@ path = "examples/z_queryable.rs"
 
 [[example]]
 name = "z_queryable_shm"
-path = "examples/z_queryable_shm.rs"
+path = "examples/shm/z_queryable_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -118,7 +121,7 @@ path = "examples/z_get.rs"
 
 [[example]]
 name = "z_get_shm"
-path = "examples/z_get_shm.rs"
+path = "examples/shm/z_get_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -147,7 +150,7 @@ path = "examples/z_sub_thr.rs"
 
 [[example]]
 name = "z_pub_shm_thr"
-path = "examples/z_pub_shm_thr.rs"
+path = "examples/shm/z_pub_shm_thr.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -156,7 +159,7 @@ path = "examples/z_ping.rs"
 
 [[example]]
 name = "z_ping_shm"
-path = "examples/z_ping_shm.rs"
+path = "examples/shm/z_ping_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
@@ -165,15 +168,25 @@ path = "examples/z_pong.rs"
 
 [[example]]
 name = "z_alloc_shm"
-path = "examples/z_alloc_shm.rs"
+path = "examples/shm/z_alloc_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
 name = "z_bytes_shm"
-path = "examples/z_bytes_shm.rs"
+path = "examples/shm/z_bytes_shm.rs"
 required-features = ["shared-memory", "unstable"]
 
 [[example]]
 name = "z_posix_shm_provider"
-path = "examples/z_posix_shm_provider.rs"
+path = "examples/shm/z_posix_shm_provider.rs"
+required-features = ["shared-memory", "unstable"]
+
+[[example]]
+name = "z_custom_shm_provider"
+path = "examples/shm/z_custom_shm_provider.rs"
+required-features = ["shared-memory", "unstable"]
+
+[[example]]
+name = "z_shm_provider"
+path = "examples/shm/z_shm_provider.rs"
 required-features = ["shared-memory", "unstable"]

examples/examples/z_alloc_shm.rs → examples/examples/shm/z_alloc_shm.rs

@@ -32,25 +32,9 @@ async fn main() {
 
 async fn run() -> zenoh::Result<()> {
     // Create an SHM provider
-    let provider = {
-        // Option 1: simple way to create default ShmProvider initialized with default-configured
-        {
-            // SHM backend (PosixShmProviderBackend)
-            let _simple =
-                ShmProviderBuilder::default_backend(MemoryLayout::try_from(42).unwrap()).wait()?;
-        }
-
-        // Option 2: comprehensive ShmProvider creation
-        {
-            // Create specific backed
-            // NOTE: For extended PosixShmProviderBackend API please check z_posix_shm_provider.rs
-            let comprehensive =
-                PosixShmProviderBackend::builder((65536, AllocAlignment::ALIGN_8_BYTES)).wait()?;
-
-            // ...and an SHM provider with specified backend
-            ShmProviderBuilder::backend(comprehensive).wait()
-        }
-    };
+    // Note: for SHM provider creation API, please see z_shm_provider.rs
+    let provider =
+        ShmProviderBuilder::default_backend((65536, AllocAlignment::ALIGN_8_BYTES)).wait()?;
 
     // Allocate SHM buffer