design/
lib.rs

1//! # *Handles* -- a Field Projection Design
2//!
3//! This crate is not only meant as a wiki and up-to-date version of the design,
4//! but also as a testing ground for new ideas. It also is very much intended to
5//! be used by people who would like to figure out if field projections can help
6//! in their use-case.
7//!
8//! <p class="warning"> This crate essentially enables writing
9//! (<code>unsafe</code>) desugared code and running it like any other Rust
10//! code. It is <strong>not</strong> designed for production, only for
11//! prototypes. It makes no guarantees on soundness, API stability, or
12//! correctness. </p>
13//!
14//! Another word of warning: writing code using this crate means manually
15//! desugaring the code that you actually wish to write; it is tedious and
16//! error-prone. But depending on your use-case, you might already be writing
17//! similarly convoluted code.
18//!
19//! ## Design Overview
20//!
21//! This design builds on top of the place centered field projection design
22//! invented by Nadrieril. The core idea that this design adds is that places
23//! are represented using *handles*. Every place expression has a corresponding
24//! handle.
25//!
26//! You can think of a handle as a pointer to the place it represents--- most of
27//! the time, that's also how it's implemented. But there also are virtual
28//! places where the handle can be a ZST. Furthermore, handles can of course
29//! contain more information than a "normal pointer", so access permissions,
30//! multiple pointers etc.
31//!
32//! ## Crate Overview
33//!
34//! This crate has the same structure as the standard library, as many parts are
35//! intended to be eventually incorporated into it. In addition, this crate also
36//! contains compatibility APIs and workarounds for language limitations that
37//! need compiler support.
38//!
39//!
40//! Here is a list of contents sorted by relevance (the most important item is
41//! the first):
42//! 1. [`ops::place`] -- all place operations that can be implemented on
43//!    handles.
44//! 2. [`place`] -- several non-operation place traits, utility types, and
45//!    handles for builtin types and local variables.
46//! 3. [`lang_limits`] -- APIs that work around compiler & language limitations,
47//!    required to write examples.
48//! 4. [`cell`], [`mem`], [`pin`], [`ptr`], [`sync`], [`mod@vec`] --
49//!    extensions to standard library modules that integrate them into the place
50//!    operations.
51//!
52//! ## Examples
53//!
54//! One of the main reasons for this crate is to showcase how code would be
55//! desugared with the current approach. In the list of crates on the left side,
56//! you can find several examples. They show both the sugared and desugared
57//! versions of the code in the documentation and are run as tests in this
58//! repository.
59//!
60//! A good starting point is the `E_simple` crate, which gives a gentle
61//! introduction into how the existing reference types would work in a place
62//! world.
63
64#![expect(incomplete_features)]
65#![allow(unused_features)]
66// Needed for proper support of `?Sized` types.
67#![feature(ptr_metadata)]
68// Needed for enum support (`&'static str` in const generics).
69#![feature(adt_const_params)]
70#![feature(unsized_const_params)]
71#![feature(sync_unsafe_cell)]
72#![feature(vec_as_non_null)]
73#![feature(proc_macro_hygiene)]
74#![feature(auto_traits)]
75#![feature(phantom_variance_markers)]
76
77pub mod boxed;
78pub mod cell;
79pub mod lang_limits;
80pub mod mem;
81pub mod ops;
82pub mod pin;
83pub mod place;
84pub mod ptr;
85pub mod sync;
86pub mod utils;
87pub mod vec;
design/lib.rs

design/
lib.rs
