Struct rocket::request::State

pub struct State<'r, T: Send + Sync + 'static>(_);

Request guard to retrieve managed state.

This type can be used as a request guard to retrieve the state Rocket is managing for some type T. This allows for the sharing of state across any number of handlers. A value for the given type must previously have been registered to be managed by Rocket via the manage method. The type being managed must be thread safe and sendable across thread boundaries. In other words, it must implement Send + Sync + 'static.

Example

Imagine you have some configuration struct of the type MyConfig that you'd like to initialize at start-up and later access it in several handlers. The following example does just this:

use rocket::State;

// In a real application, this would likely be more complex.
struct MyConfig {
    user_val: String
}

#[get("/")]
fn index(state: State<MyConfig>) -> String {
    format!("The config value is: {}", state.user_val)
}

#[get("/raw")]
fn raw_config_value<'r>(state: State<'r, MyConfig>) -> &'r str {
    // use `inner()` to get a lifetime longer than `deref` gives us
    state.inner().user_val.as_str()
}

fn main() {
    let config = MyConfig {
        user_val: "user input".to_string()
    };

    rocket::ignite()
        .mount("/", routes![index, raw_config_value])
        .manage(config)
        .launch();
}

Within Request Guards

Because State is itself a request guard, managed state can be retrieved from another request guard's implementation. In the following code example, Item retrieves the MyConfig managed state in its FromRequest implementation using the Request::guard() method.

use rocket::State;
use rocket::request::{self, Request, FromRequest};

struct Item(String);

impl<'a, 'r> FromRequest<'a, 'r> for Item {
    type Error = ();

    fn from_request(request: &'a Request<'r>) -> request::Outcome<Item, ()> {
        request.guard::<State<MyConfig>>()
            .map(|my_config| Item(my_config.user_val.clone()))
    }
}

Methods

impl<'r, T: Send + Sync + 'static> State<'r, T>

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

pub fn inner(&self) -> &'r T

Retrieve a borrow to the underyling value with a lifetime of 'r.

Using this method is typically unnecessary as State implements Deref with a Target of T. This means Rocket will automatically coerce a State<T> to an &T as required. This method should only be used when a longer lifetime is required.

Example

use rocket::State;

struct MyConfig {
    user_val: String
}

// Use `inner()` to get a lifetime of `'r`
fn handler1<'r>(config: State<'r, MyConfig>) -> &'r str {
    &config.inner().user_val
}

// Use the `Deref` implementation which coerces implicitly
fn handler2(config: State<MyConfig>) -> String {
    config.user_val.clone()
}

Trait Implementations

impl<'r, T: Debug + Send + Sync + 'static> Debug for State<'r, T>

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

Formats the value using the given formatter.

impl<'r, T: PartialEq + Send + Sync + 'static> PartialEq for State<'r, T>

fn eq(&self, other: &State<'r, T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &State<'r, T>) -> bool

This method tests for !=.

impl<'r, T: Eq + Send + Sync + 'static> Eq for State<'r, T>

impl<'r, T: PartialOrd + Send + Sync + 'static> PartialOrd for State<'r, T>

fn partial_cmp(&self, other: &State<'r, T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &State<'r, T>) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &State<'r, T>) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &State<'r, T>) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &State<'r, T>) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<'r, T: Ord + Send + Sync + 'static> Ord for State<'r, T>

fn cmp(&self, other: &State<'r, T>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl<'r, T: Hash + Send + Sync + 'static> Hash for State<'r, T>

fn hash<__HT: Hasher>(&self, state: &mut __HT)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where     H: Hasher,

Feeds a slice of this type into the given [Hasher].

impl<'a, 'r, T: Send + Sync + 'static> FromRequest<'a, 'r> for State<'r, T>

type Error = ()

The associated error to be returned if derivation fails.

fn from_request(req: &'a Request<'r>) -> Outcome<State<'r, T>, ()>

Derives an instance of Self from the incoming request metadata.

impl<'r, T: Send + Sync + 'static> Deref for State<'r, T>

type Target = T

The resulting type after dereferencing.

Important traits for &'a mut R

impl<'a, R> Read for &'a mut R where
    R: Read + ?Sized, impl<'a, W> Write for &'a mut W where
    W: Write + ?Sized, impl<'a, I> Iterator for &'a mut I where
    I: Iterator + ?Sized,  type Item = <I as Iterator>::Item;

fn deref(&self) -> &T

Dereferences the value.