Struct rocket::State

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

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;

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(());

        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§

source§

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

source

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);
source

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§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

§

type Target = T

The resulting type after dereferencing.
source§

fn deref(&self) -> &T

Dereferences the value.
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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

Converts to this type from the input type.
source§

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

§

type Error = ()

The associated error to be returned if derivation fails.
source§

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. Read more
source§

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

source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · source§

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

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

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

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval. Read more
source§

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

source§

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

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

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.
source§

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

source§

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

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

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

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

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

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

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

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

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

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

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

§

type From = T

source§

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

source§

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

source§

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

source§

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

Returns true if launch should be aborted and false otherwise.
source§

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

source§

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

source§

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

Auto Trait Implementations§

§

impl<T> RefUnwindSafe for State<T>where T: RefUnwindSafe,

§

impl<T> Send for State<T>

§

impl<T> Sync for State<T>

§

impl<T> Unpin for State<T>where T: Unpin,

§

impl<T> UnwindSafe for State<T>where T: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<'a, T> AsTaggedExplicit<'a> for Twhere T: 'a,

§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self>

§

impl<'a, T> AsTaggedImplicit<'a> for Twhere T: 'a,

§

fn implicit( self, class: Class, constructed: bool, tag: u32 ) -> TaggedParser<'a, Implicit, Self>

source§

impl<T> Borrow<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

const: unstable · source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> CallHasher for Twhere T: Hash + ?Sized,

§

default fn get_hash<H, B>(value: &H, build_hasher: &B) -> u64where H: Hash + ?Sized, B: BuildHasher,

source§

impl<Q, K> Equivalent<K> for Qwhere Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

source§

fn equivalent(&self, key: &K) -> bool

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

impl<T> From<T> for T

const: unstable · source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for Twhere U: From<T>,

const: unstable · source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> IntoCollection<T> for T

§

fn into_collection<A>(self) -> SmallVec<A>where A: Array<Item = T>,

Converts self into a collection.
§

fn mapped<U, F, A>(self, f: F) -> SmallVec<A>where F: FnMut(T) -> U, A: Array<Item = U>,

source§

impl<T> Same<T> for T

§

type Output = T

Should always be Self
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
const: unstable · source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
const: unstable · source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> Formattable for Twhere T: Deref, <T as Deref>::Target: Formattable,

source§

impl<T> Parsable for Twhere T: Deref, <T as Deref>::Target: Parsable,