Struct rocket::State [] [src]

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>
[src]

[src]

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>
[src]

[src]

Formats the value using the given formatter.

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

[src]

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

[src]

This method tests for !=.

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

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

[src]

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

[src]

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

[src]

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

[src]

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

[src]

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

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

[src]

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

1.22.0
[src]

Compares and returns the maximum of two values. Read more

1.22.0
[src]

Compares and returns the minimum of two values. Read more

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

[src]

Feeds this value into the given [Hasher]. Read more

1.3.0
[src]

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

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

The associated error to be returned if derivation fails.

[src]

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

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

The resulting type after dereferencing.

[src]

Dereferences the value.