paradis_core

Trait ParAccess

Source 
pub unsafe trait ParAccess<Index: Copy>: Sync + Send {
    type Record: Send;

    // Required methods
    unsafe fn clone_access(&self) -> Self;
    unsafe fn get_unsync_unchecked(&self, index: Index) -> Self::Record;
}
Expand description

Unsynchronized access to records in a collection.

The trait provides unsynchronized access to records, defined by the associated Record type, that are indexed by the Index parameter. This trait gives data structures a means to give users unfettered access to its records, without exposing internal implementation details to the user. In turn, it is the responsibility of the user to maintain the invariants of Rust’s memory safety model.

An access object for a data structure is usually a lightweight wrapper around one or more pointers, plus necessary metadata.

In order to use higher-level functionality in paradis, implementors should try to implement BoundedParAccess too, whenever possible.

§Safety

A user must ensure that a record — accessed by the same index — is only accessed once, at any given time. It may be helpful to imagine that Record is a mutable reference, &mut T, and so it is undefined behavior to obtain two mutable references to the same object. In other words, once a specific Record is accessed, it can not be accessed through this access object again until the previous instance is dropped.

An implementor must ensure that, for as long as any access object exists, the size of the data structure remains unchanged, and that the same index always refers to the same “slot” in the data structure.

§Notes on design

In an early iteration of paradis, Record was not required to implement Send. The idea was that you should be able to use the abstraction also in single-threaded scenarios, possibly with types that are not Send. However, since we want ParAccess to be Send and Sync, this could lead to unsoundness because moving an access object into a thread would allow us to create, say, a single-threaded iterator to records in that thread, even though those records were not constrained to be Send. To eliminate problems like these, we therefore require that Record implements Send.

Required Associated Types§

Source

type Record: Send

A record (element) in the underlying collection.

Required Methods§

Source

unsafe fn clone_access(&self) -> Self

Clones this access.

§Safety

This is unsafe, because methods that consume access objects typically assume that the access is exclusive. If the access is cloned, then the user must ensure that the invariants are uphold across all active accesses. Typically, this is achieved by having each access work on disjoint sets of records.

Source

unsafe fn get_unsync_unchecked(&self, index: Index) -> Self::Record

Unsynchronized lookup of record without bounds checks.

§Safety

See trait documentation.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§