Struct rocket::request::State[−][src]

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

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 Rocket::manage(). 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()))
    }
}

Testing with State

When unit testing your application, you may find it necessary to manually construct a type of State to pass to your functions. To do so, use the State::from() static method:

use rocket::State;

struct MyManagedState(usize);

#[get("/")]
fn handler(state: State<MyManagedState>) -> String {
    state.0.to_string()
}

let rocket = rocket::ignite().manage(MyManagedState(127));
let state = State::from(&rocket).expect("managing `MyManagedState`");
assert_eq!(handler(state), "127");

Implementations

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

Using this method is typically unnecessary as State implements Deref with a Deref::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()
}

Returns the managed state value in rocket for the type T if it is being managed by rocket. Otherwise, returns None.

Example

use rocket::State;

#[derive(Debug, PartialEq)]
struct Managed(usize);

#[derive(Debug, PartialEq)]
struct Unmanaged(usize);

let rocket = rocket::ignite().manage(Managed(7));

let state: Option<State<Managed>> = State::from(&rocket);
assert_eq!(state.map(|s| s.inner()), Some(&Managed(7)));

let state: Option<State<Unmanaged>> = State::from(&rocket);
assert_eq!(state, None);

Trait Implementations

Formats the value using the given formatter. Read more

The resulting type after dereferencing.

Dereferences the value.

The associated error to be returned if derivation fails.

Derives an instance of Self from the incoming request metadata. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

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

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

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

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Compare self to key and return true if they are equal.

Performs the conversion.

Performs the conversion.

Converts self into a collection.

Should always be Self

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Get the TypeId of this object.