[−][src]Module rocket::outcome
Success, failure, and forward handling.
The Outcome<S, E, F> type is similar to the standard library's Result<S, E> type. It is an enum with three variants, each containing a value:
Success(S), which represents a successful outcome, Failure(E), which
represents a failing outcome, and Forward(F), which represents neither a
success or failure, but instead, indicates that processing could not be
handled and should instead be forwarded to whatever can handle the
processing next.
The Outcome type is the return type of many of the core Rocket traits,
including FromRequest,
FromData, and Responder. It
is also the return type of request handlers via the Response type.
Success
A successful Outcome<S, E, F>, Success(S), is returned from functions
that complete successfully. The meaning of a Success outcome depends on
the context. For instance, the Outcome of the from_data method of the
FromData trait will be matched against the type expected by the user. For
example, consider the following handler:
#[post("/", data = "<my_val>")] fn hello(my_val: S) -> ... { }
The FromData implementation for the type S returns an Outcome with a
Success(S). If from_data returns a Success, the Success value will
be unwrapped and the value will be used as the value of my_val.
Failure
A failure Outcome<S, E, F>, Failure(E), is returned when a function
fails with some error and no processing can or should continue as a result.
The meaning of a failure depends on the context.
In Rocket, a Failure generally means that a request is taken out of normal
processing. The request is then given to the catcher corresponding to some
status code. Users can catch failures by requesting a type of Result<S, E>
or Option<S> in request handlers. For example, if a user's handler looks
like:
#[post("/", data = "<my_val>")] fn hello(my_val: Result<S, E>) -> ... { }
The FromData implementation for the type S returns an Outcome with a
Success(S) and Failure(E). If from_data returns a Failure, the
Failure value will be unwrapped and the value will be used as the Err
value of my_val while a Success will be unwrapped and used the Ok
value.
Forward
A forward Outcome<S, E, F>, Forward(F), is returned when a function
wants to indicate that the requested processing should be forwarded to the
next available processor. Again, the exact meaning depends on the context.
In Rocket, a Forward generally means that a request is forwarded to the
next available request handler. For example, consider the following request
handler:
#[post("/", data = "<my_val>")] fn hello(my_val: S) -> ... { }
The FromData implementation for the type S returns an Outcome with a
Success(S), Failure(E), and Forward(F). If the Outcome is a
Forward, the hello handler isn't called. Instead, the incoming request
is forwarded, or passed on to, the next matching route, if any. Ultimately,
if there are no non-forwarding routes, forwarded requests are handled by the
404 catcher. Similar to Failures, users can catch Forwards by requesting
a type of Option<S>. If an Outcome is a Forward, the Option will be
None.
Enums
| Outcome | An enum representing success ( |
Traits
| IntoOutcome | Conversion trait from some type into an Outcome type. |