About

This crate strives to implement unique linear types.

The [Linear<T>] type that wraps a T. Linear types must not be dropped but eventualy consumed. There are only a few methods you can use on a linear type.

• new_linear!() creates a new linear type. Must be a macro for unique types.
• into_inner() destructures a object returning the inner T.
• destroy() manual drop method, consumes and destroys the wrapped inner type.
• map() applies a FnOnce with the destructured inner type as parameter yielding another linear type.
• Some variants of map() to handle Linear<Result<T,E>> and Linear<Option<T>>.
• Linear<Result<T,E>> and Linear<Option<T>> support few forms of unwrap().
• splice() and merge() to divert and join the program flow of unique types.

Unlike Pin, linear types can be moved, and unlike ManuallyDrop, linear types are required to be eventually deconstructed and consumed.

Strict linearity is enforced by creating unique types for each linear type which track the operations that are applied on the values. They are tagged #[must_use], when one still tries to drop a linear type by let _ = ... or drop() a runtime panic happens. Unfortunally there is no way to detect this at compile time in stable rust.

Dropping Policy and Panics

Panicking is inherently incompatible with a linear type system. Still rust relies on the fact that panics can basically happen at any time. We face the situation that we have to mix standard rust with a linear type system.

Linear types are ordinary rust types. When panics happen then the all state is properly unwinded and destructors are called, even for the inners of linear types. This is only modestly sound but the best we can do.

Status

This crate started with a discussion on IRC. It does not completey implement pure linear-type theory as this would require language support. Consider it as proof-of-concept. Most notably using mem::forget() on a linear type will break the linear type semantics. This crate can not prevent this. It may have some use and should be safe (in the Rust sense) to use. Improvements and PR's are welcome. This crate will be somewhat in flux before a 1.0 version is released.

Creating unique types for each new linear type and each operation on it is expected to be heavy on the type system. Don't expect it to be fast and slim to compile. If possible enable LTO in release builds since it may reduce the footprint of monomorphized functions significantly.

Feature Flags

• drop_unchecked

  When this crate is compiled with the drop_unchecked feature flag, then, in release builds, dropping a linear type will not panic as intended. The linear-type semantic is not enforced. This defeats the purpose of this crate. It adds only a small space and performance improvement. It should considered to be UB and should only be enabled on programs that are thoroughly validated and tested when required.

• semipure

  When this crate is compiled with the semipure feature flag, then the Linear<T> type will implement the get_ref() method. This method will return a reference to the inner value. This is useful when you want to borrow the inner value without consuming the linear type. This feature is not recommended as it may break the linear type semantics.

Example

While any type can be wraped in a Linear<T>, it is recommended to use it with unique newtypes which transitioning into a final state. The state transitions can be functions or closures.

use linear_type::*;
use std::fs::File;
use std::io::{Read, Result};

// define some newtypes for the states
struct Filename(&'static str);
#[derive(Debug)]
struct ReadonlyFile(File);
#[derive(Debug)]
struct FileContent(String);

// define functions that transition from one state to the next.
fn open_file(Filename(name): Filename) -> Result<ReadonlyFile> {
    Ok(ReadonlyFile(File::open(name)?))
}

fn read_text(ReadonlyFile(mut file): ReadonlyFile) -> Result<FileContent> {
    let mut text = String::new();
    file.read_to_string(&mut text)?;
    Ok(FileContent(text))
}

fn main() {
    // Create a linear type and transition through the states
    let file_content = new_linear!(Filename("README.md"))
        .map(open_file)
        .map_ok(read_text)
        .unwrap_ok();

    // destructure the file content
    let FileContent(text) = file_content.into_inner();
    assert!(text.contains("# Example"));
}