Struct NativeRegion 

pub struct NativeRegion { /* private fields */ }

Common owner of the best private native shared-memory object on this target.

It exposes logical initialization bytes only through a closure. Consuming NativeRegion::prepare_for_sharing hands the region to the existing authenticated platform transfer typestate, which applies real native seals and exact permissions. Growth and arbitrary permission changes are no longer possible after that transition.

Implementations

impl NativeRegion

pub fn allocate(options: RegionOptions) -> Result<Self, MemoryError>

Allocates a zeroed, anonymous, non-executable native region.

Examples found in repository

examples/common_memory.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub const fn options(&self) -> RegionOptions

Returns the immutable allocation and authority policy.

pub fn status(&self) -> RegionStatus

Returns a portable status snapshot.

Examples found in repository

examples/common_memory.rs (line 14)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub fn initialize<R>(&mut self, operation: impl FnOnce(&mut [u8]) -> R) -> R

Runs one initialization operation over logical bytes only.

Page-rounded padding remains zero and inaccessible through this common method. No capability has escaped while the closure runs.

Examples found in repository

examples/common_memory.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub fn clear(&mut self)

Clears the complete page-rounded mapping and retains it for reuse.

Every byte, including native page padding, is overwritten through the live mapping before this method returns.

Examples found in repository

examples/common_memory.rs (line 24)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub fn grow(&mut self, requested: usize) -> Result<(), MemoryError>

Grows by replacing the still-private mapping and preserving logical bytes.

Examples found in repository

examples/common_memory.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub fn close(self)

Explicitly clears according to policy and releases the anonymous object.

pub fn destroy(self)

Overwrites the complete mapping, then explicitly releases it.

This ignores CleanupPolicy and always performs the clearing pass. It cannot erase copies previously made by a process, the kernel, or a device. The region must still be quiescent and exclusively owned here; shared regions are destroyed by their transferred lifecycle owner.

Examples found in repository

examples/common_memory.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let capabilities = native_memory_capabilities();
    let options = RegionOptions::growable(128, 4096, WriterOwner::Creator);
    let mut region = NativeRegion::allocate(options)?;

    region.initialize(|bytes| bytes[..8].copy_from_slice(b"NIPCDEMO"));
    region.grow(512)?;
    region.initialize(|bytes| assert_eq!(&bytes[..8], b"NIPCDEMO"));

    let status = region.status();
    println!(
        "backend={:?} authority={:?} logical={} mapped={} maximum={}",
        capabilities.platform(),
        capabilities.authority_mechanism(),
        status.logical_len,
        status.mapped_len,
        status.maximum_len,
    );

    region.clear();
    region.initialize(|bytes| bytes[..8].copy_from_slice(b"REUSABLE"));

    // `destroy` explicitly clears the complete mapping before releasing it.
    // Use `prepare_for_sharing` instead when handing the region to the
    // authenticated platform transfer typestate.
    region.destroy();
    Ok(())
}

pub fn prepare_for_sharing(self) -> NativeShareRequest

Freezes common initialization/growth and creates a native share request.

The request retains the permission and mandatory seal policy alongside the native region. Its platform parts must be consumed by the matching authenticated prepare/transfer operation.

Trait Implementations

impl Drop for NativeRegion

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.