Struct rocket::State

pub struct State<T: Send + Sync + 'static>(/* private fields */);

Request guard to retrieve managed state.

A reference &State<T> type is a request guard which retrieves the managed state managing for some type T. 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 as multiple handlers in multiple threads may be accessing the value at once. 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(state: &State<MyConfig>) -> &str {
    &state.user_val
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", routes![index, raw_config_value])
        .manage(MyConfig { user_val: "user input".to_string() })
}

Within Request Guards

Because State is itself a request guard, managed state can be retrieved from another request guard’s implementation using either Request::guard() or Rocket::state(). In the following code example, the Item request guard retrieves MyConfig from managed state:

use rocket::State;
use rocket::request::{self, Request, FromRequest};
use rocket::outcome::IntoOutcome;
use rocket::http::Status;

struct Item<'r>(&'r str);

#[rocket::async_trait]
impl<'r> FromRequest<'r> for Item<'r> {
    type Error = ();

    async fn from_request(request: &'r Request<'_>) -> request::Outcome<Self, ()> {
        // Using `State` as a request guard. Use `inner()` to get an `'r`.
        let outcome = request.guard::<&State<MyConfig>>().await
            .map(|my_config| Item(&my_config.user_val));

        // Or alternatively, using `Rocket::state()`:
        let outcome = request.rocket().state::<MyConfig>()
            .map(|my_config| Item(&my_config.user_val))
            .or_forward(Status::InternalServerError);

        outcome
    }
}

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::get() static method or the From<&T> implementation:

use rocket::State;

struct MyManagedState(usize);

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

let mut rocket = rocket::build().manage(MyManagedState(127));
let state = State::get(&rocket).expect("managed `MyManagedState`");
assert_eq!(handler(state), "127");

let managed = MyManagedState(77);
assert_eq!(handler(State::from(&managed)), "77");

Implementations

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

pub fn get<P: Phase>(rocket: &Rocket<P>) -> Option<&State<T>>

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::build().manage(Managed(7));

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

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

pub fn inner(&self) -> &T

Borrow the inner value.

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;

#[derive(Clone)]
struct MyConfig {
    user_val: String
}

fn handler1<'r>(config: &State<MyConfig>) -> String {
    let config = config.inner().clone();
    config.user_val
}

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

Trait Implementations

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

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

Formats the value using the given formatter.

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

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: Send + Sync + Display + 'static> Display for State<T>

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

Formats the value using the given formatter.

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

fn from(reference: &'r T) -> Self

Converts to this type from the input type.

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

type Error = ()

The associated error to be returned if derivation fails.

fn from_request<'life0, 'async_trait>( req: &'r Request<'life0> ) -> Pin<Box<dyn Future<Output = Outcome<Self, ()>> + Send + 'async_trait>>

where Self: 'async_trait, 'r: 'async_trait, 'life0: 'async_trait,

Derives an instance of Self from the incoming request metadata.

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

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

Feeds this value into the given Hasher.

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

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

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

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

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

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

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

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl<T: Send + Sync + 'static> RefCast for State<T>

type From = T

fn ref_cast(_from: &Self::From) -> &Self

fn ref_cast_mut(_from: &mut Self::From) -> &mut Self

impl<T: Send + Sync + 'static> Sentinel for &State<T>

fn abort(rocket: &Rocket<Ignite>) -> bool

Returns true if launch should be aborted and false otherwise.

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

impl<T: Send + Sync + 'static> StructuralPartialEq for State<T>