Trait PtrCfg

Source

pub trait PtrCfg: Sealed + Default {
    // Required methods
    fn lsb_bits<T>() -> usize;
    fn msb_bits() -> usize;

    // Provided method
    fn bits<T>() -> usize { ... }
}

Expand description

A configuration for a PackedPtr.

This trait is sealed and cannot be implemented outside of this crate. Implementations are provided for various platforms.

There are 2 types of PtrCfgs that are available for all platforms:

None: No data can be packed into the pointer. This configuration will always fail when packing data into a pointer.
AlignOnly: Only the alignment of the pointer can be packed into the pointer. This configuration will use the alignment of a pointer to determine how many bits can be packed into the LSBs of the pointer.

A pointer can pack data into 2 places in a pointer: the LSB bits & the MSB bits.

The LSB bits use the fact that data has a ABI-defined minimum alignment. That means pointers to data must be a multiple of that alignment. For example, u32 has a minimum alignment of 4, so the last 2 bits of a pointer to a u32 will always be 0. We can use those 2 bits to store data. This method is safe as long as the pointer is aligned.

The MSB bits use the fact that 64-bit architectures don’t actually use all 64 bits of a pointer. For example, on x86_64, most CPUs only use the lower 48 bits of a pointer. Most ISA’s specify that the upper bits of a pointer must be all 0s or all 1s. And most OS’s specify that the address space of userspace processes must be in the lower half of the address space. We can use these upper unused bits to store even more data in the pointer, as long as we return the pointer back to all 0s before de-referencing it.

Of course, the amount of the MSB bits is platform-specific, OS-specific, and CPU-specific. So it is the responsibility of the user to ensure that the pointer & config combination they use is safe. However, we can perform checks at runtime to ensure that the provided pointer can be safely converted into a PackedPtr with the provided config.