Struct Handle

pub struct Handle { /* private fields */ }

A Handle we allow to be returned over the FFI by implementing IntoFfi. This type is intentionally not #[repr(C)], and getting the data out of the FFI is done using Handle::from_u64, or it’s implemetation of From<u64>.

It consists of, at a minimum:

• A “map id” (used to ensure you’re using it with the correct map)
• a “version” (incremented when the value in the index changes, used to detect multiple frees, use after free, and ABA and ABA)
• and a field indicating which index it goes into.

In practice, it may also contain extra information to help detect other errors (currently it stores a “magic value” used to detect invalid Handles).

These fields may change but the following guarantees are made about the internal representation:

• This will always be representable in 64 bits.
• The bits, when interpreted as a signed 64 bit integer, will be positive (that is to say, it will actually be representable in 63 bits, since this makes the most significant bit unavailable for the purposes of encoding). This guarantee makes things slightly less dubious when passing things to Java, gives us some extra validation ability, etc.

Implementations

impl Handle

pub fn into_u64(self) -> u64

Convert a Handle to a u64. You can also use Into::into directly. Most uses of this will be automatic due to our IntoFfi implementation.

pub fn from_u64(v: u64) -> Result<Self, HandleError>

Convert a u64 to a Handle. Inverse of into_u64. We also implement From::from (which will panic instead of returning Err).

Returns HandleError::InvalidHandle if the bits cannot possibly represent a valid handle.

pub fn is_valid(v: u64) -> bool

Returns whether or not v makes a bit pattern that could represent an encoded Handle.

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Handle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Handle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Handle> for u64

fn from(h: Handle) -> u64

Converts to this type from the input type.

impl From<u64> for Handle

fn from(u: u64) -> Self

Converts to this type from the input type.

impl<T> Index<Handle> for HandleMap<T>

type Output = T

The returned type after indexing.

fn index(&self, h: Handle) -> &T

Performs the indexing (container[index]) operation.

impl IntoFfi for Handle

type Value = u64

This type must be:

fn ffi_default() -> u64

Return an ‘empty’ value. This is what’s passed back to C in the case of an error, so it doesn’t actually need to be “empty”, so much as “ignorable”. Note that this is also used when an empty Option<T> is returned.

fn into_ffi_value(self) -> u64

Convert ourselves into a value we can pass back to C with confidence.

impl PartialEq for Handle

fn eq(&self, other: &Handle) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Handle

impl StructuralPartialEq for Handle