Enum r3_core::kernel::ResultCode

#[repr(i8)]
#[non_exhaustive]
pub enum ResultCode {
    Success,
    NotSupported,
    BadParam,
    NoAccess,
    BadContext,
    NotOwner,
    WouldDeadlock,
    BadObjectState,
    QueueOverflow,
    Abandoned,
    Interrupted,
    Timeout,
}

All result codes (including the one indicating success) that a kernel function can return.

Relation to Other Specifications: The error variants were loosely inspired from μITRON4.0 for no particular reasons.

Rationale: Giving them explicit and stable discriminants makes it possible to produce them directly in foreign code.

The discriminants are assigned in a way that maximizes the execution efficiency based on the following assumptions:

• Some variants, such as BadContext and NoAccess, are more likely to be handled by unwrap-ing than other variants. Therefore, sorting their u8 interpretations in the increasing order of the likelihood of being handled by unwrap-ing increases the likelihood of the evaluation of an unwrap condition being compiled down to a single integer comparison.

• The discriminants are tightly arranged so that the membership test with a compile-time result code set can be implemented by a bitfield look-up table on a general-purpose register.

• Most of the error types including subsets of ResultCode include BadContext, hence by assigning -1 to it, Result<(), $ErrorType>::Ok will get 0 as its discriminant, which improves the execution efficiency because comparison to zero can be done efficiently on most instruction set architectures.

Stability

This type is covered by the application-side API stability guarantee. The explicit discriminants are only covered by the kernel-side API stability guarantee. Adding new variants or changing the representation size is not considered a breaking change.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Success

The operation was successful. No additional information is available.

NotSupported

The operation is not supported.

BadParam

A parameter is invalid in a way that is no covered by any other error codes.

NoAccess

The current operation was rejected by an optional protection mechanism, e.g., because the specified object identifier (Id) is invalid, or the caller lacks the necessary privileges to complete the operation.

This error usually indicates an object safety or memory safety violation. A kernel implementation is not required to report this as it’s not practical in general cases. It’s strongly recommended that application code not rely on this error code being returned and, should it be returned, escalate it to a panic or abort immediately unless the code is written for a specific kernel implementation that makes a special provision.

Rationale: In the original design, R3 was limited to a specific kernel implementation, and this kernel implementation always validated input object identifiers as it was trivial to do so. Now that R3 is being redesigned as a pure interface for unknown kernels, requiring this property might pose a considerable burden on kernel implementations. In addition, the provided object handle types enforces object safety, and creating them from raw object IDs is impossible in safe code. It’s for this reason that detecting this error is now optional.

One of the avenues being explored is to support RTOS kernels with a security-oriented protection mechanism. From a security point of view, it’s preferable not to disclose the state of other protection domains (e.g., if the object IDs were memory addresses, exposing them would undermine the security benefits of address space layout randomization), hence the intentional lack of error code distinction between invalid IDs and inaccessible IDs.

Since it’s most likely escalated to a panic or abort, it was also considered to remove this error code altogether. However, since error codes are not extensible, this would unnecessarily complicate the rare cases where it can be reasonably handled in other ways.

BadContext

The current context disallows the operation.

NotOwner

The caller does not own the resource.

WouldDeadlock

Resource deadlock would occur.

BadObjectState

A target object is in a state that disallows the operation.

QueueOverflow

An operation or an object couldn’t be enqueued because there are too many of such things that already have been enqueued.

Abandoned

The owner of a mutex exited while holding the mutex lock.

Interrupted

The wait operation was interrupted by Task::interrupt.

Timeout

The operation timed out.

Implementations

impl ResultCode

pub fn as_str(self) -> &'static str

Get the short name of the result code.

Examples

use r3_core::kernel::ResultCode;
assert_eq!(ResultCode::BadObjectState.as_str(), "BadObjectState");

impl ResultCode

pub fn is_err(self) -> bool

Get a flag indicating whether the code represents a failure.

Failure codes have negative values.

pub fn is_ok(self) -> bool

Get a flag indicating whether the code represents a success.

Success codes have non-negative values.

Trait Implementations

impl Clone for ResultCode

fn clone(&self) -> ResultCode

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ResultCode

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

Formats the value using the given formatter.

impl From<ActivateTaskError> for ResultCode

fn from(x: ActivateTaskError) -> Self

Converts to this type from the input type.

impl From<AdjustTimeError> for ResultCode

fn from(x: AdjustTimeError) -> Self

Converts to this type from the input type.

impl From<BoostPriorityError> for ResultCode

fn from(x: BoostPriorityError) -> Self

Converts to this type from the input type.

impl From<ClearInterruptLineError> for ResultCode

fn from(x: ClearInterruptLineError) -> Self

Converts to this type from the input type.

impl From<CpuLockError> for ResultCode

fn from(x: CpuLockError) -> Self

Converts to this type from the input type.

impl From<DrainSemaphoreError> for ResultCode

fn from(x: DrainSemaphoreError) -> Self

Converts to this type from the input type.

impl From<EnableInterruptLineError> for ResultCode

fn from(x: EnableInterruptLineError) -> Self

Converts to this type from the input type.

impl From<ExitTaskError> for ResultCode

fn from(x: ExitTaskError) -> Self

Converts to this type from the input type.

impl From<GetCurrentTaskError> for ResultCode

fn from(x: GetCurrentTaskError) -> Self

Converts to this type from the input type.

impl From<GetEventGroupError> for ResultCode

fn from(x: GetEventGroupError) -> Self

Converts to this type from the input type.

impl From<GetSemaphoreError> for ResultCode

fn from(x: GetSemaphoreError) -> Self

Converts to this type from the input type.

impl From<GetTaskPriorityError> for ResultCode

fn from(x: GetTaskPriorityError) -> Self

Converts to this type from the input type.

impl From<InterruptTaskError> for ResultCode

fn from(x: InterruptTaskError) -> Self

Converts to this type from the input type.

impl From<LockMutexError> for ResultCode

fn from(x: LockMutexError) -> Self

Converts to this type from the input type.

impl From<LockMutexTimeoutError> for ResultCode

fn from(x: LockMutexTimeoutError) -> Self

Converts to this type from the input type.

impl From<MarkConsistentMutexError> for ResultCode

fn from(x: MarkConsistentMutexError) -> Self

Converts to this type from the input type.

impl From<ParkError> for ResultCode

fn from(x: ParkError) -> Self

Converts to this type from the input type.

impl From<ParkTimeoutError> for ResultCode

fn from(x: ParkTimeoutError) -> Self

Converts to this type from the input type.

impl From<PendInterruptLineError> for ResultCode

fn from(x: PendInterruptLineError) -> Self

Converts to this type from the input type.

impl From<PollEventGroupError> for ResultCode

fn from(x: PollEventGroupError) -> Self

Converts to this type from the input type.

impl From<PollSemaphoreError> for ResultCode

fn from(x: PollSemaphoreError) -> Self

Converts to this type from the input type.

impl From<QueryInterruptLineError> for ResultCode

fn from(x: QueryInterruptLineError) -> Self

Converts to this type from the input type.

impl From<QueryMutexError> for ResultCode

fn from(x: QueryMutexError) -> Self

Converts to this type from the input type.

impl From<Result<(), ActivateTaskError>> for ResultCode

fn from(x: Result<(), ActivateTaskError>) -> Self

Converts to this type from the input type.

impl From<Result<(), AdjustTimeError>> for ResultCode

fn from(x: Result<(), AdjustTimeError>) -> Self

Converts to this type from the input type.

impl From<Result<(), BoostPriorityError>> for ResultCode

fn from(x: Result<(), BoostPriorityError>) -> Self

Converts to this type from the input type.

impl From<Result<(), ClearInterruptLineError>> for ResultCode

fn from(x: Result<(), ClearInterruptLineError>) -> Self

Converts to this type from the input type.

impl From<Result<(), CpuLockError>> for ResultCode

fn from(x: Result<(), CpuLockError>) -> Self

Converts to this type from the input type.

impl From<Result<(), DrainSemaphoreError>> for ResultCode

fn from(x: Result<(), DrainSemaphoreError>) -> Self

Converts to this type from the input type.

impl From<Result<(), EnableInterruptLineError>> for ResultCode

fn from(x: Result<(), EnableInterruptLineError>) -> Self

Converts to this type from the input type.

impl From<Result<(), ExitTaskError>> for ResultCode

fn from(x: Result<(), ExitTaskError>) -> Self

Converts to this type from the input type.

impl From<Result<(), GetCurrentTaskError>> for ResultCode

fn from(x: Result<(), GetCurrentTaskError>) -> Self

Converts to this type from the input type.

impl From<Result<(), GetEventGroupError>> for ResultCode

fn from(x: Result<(), GetEventGroupError>) -> Self

Converts to this type from the input type.

impl From<Result<(), GetSemaphoreError>> for ResultCode

fn from(x: Result<(), GetSemaphoreError>) -> Self

Converts to this type from the input type.

impl From<Result<(), GetTaskPriorityError>> for ResultCode

fn from(x: Result<(), GetTaskPriorityError>) -> Self

Converts to this type from the input type.

impl From<Result<(), InterruptTaskError>> for ResultCode

fn from(x: Result<(), InterruptTaskError>) -> Self

Converts to this type from the input type.

impl From<Result<(), LockMutexError>> for ResultCode

fn from(x: Result<(), LockMutexError>) -> Self

Converts to this type from the input type.

impl From<Result<(), LockMutexTimeoutError>> for ResultCode

fn from(x: Result<(), LockMutexTimeoutError>) -> Self

Converts to this type from the input type.

impl From<Result<(), MarkConsistentMutexError>> for ResultCode

fn from(x: Result<(), MarkConsistentMutexError>) -> Self

Converts to this type from the input type.

impl From<Result<(), ParkError>> for ResultCode

fn from(x: Result<(), ParkError>) -> Self

Converts to this type from the input type.

impl From<Result<(), ParkTimeoutError>> for ResultCode

fn from(x: Result<(), ParkTimeoutError>) -> Self

Converts to this type from the input type.

impl From<Result<(), PendInterruptLineError>> for ResultCode

fn from(x: Result<(), PendInterruptLineError>) -> Self

Converts to this type from the input type.

impl From<Result<(), PollEventGroupError>> for ResultCode

fn from(x: Result<(), PollEventGroupError>) -> Self

Converts to this type from the input type.

impl From<Result<(), PollSemaphoreError>> for ResultCode

fn from(x: Result<(), PollSemaphoreError>) -> Self

Converts to this type from the input type.

impl From<Result<(), QueryInterruptLineError>> for ResultCode

fn from(x: Result<(), QueryInterruptLineError>) -> Self

Converts to this type from the input type.

impl From<Result<(), QueryMutexError>> for ResultCode

fn from(x: Result<(), QueryMutexError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SetInterruptLinePriorityError>> for ResultCode

fn from(x: Result<(), SetInterruptLinePriorityError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SetTaskPriorityError>> for ResultCode

fn from(x: Result<(), SetTaskPriorityError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SetTimerDelayError>> for ResultCode

fn from(x: Result<(), SetTimerDelayError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SetTimerPeriodError>> for ResultCode

fn from(x: Result<(), SetTimerPeriodError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SignalSemaphoreError>> for ResultCode

fn from(x: Result<(), SignalSemaphoreError>) -> Self

Converts to this type from the input type.

impl From<Result<(), SleepError>> for ResultCode

fn from(x: Result<(), SleepError>) -> Self

Converts to this type from the input type.

impl From<Result<(), StartTimerError>> for ResultCode

fn from(x: Result<(), StartTimerError>) -> Self

Converts to this type from the input type.

impl From<Result<(), StopTimerError>> for ResultCode

fn from(x: Result<(), StopTimerError>) -> Self

Converts to this type from the input type.

impl From<Result<(), TimeError>> for ResultCode

fn from(x: Result<(), TimeError>) -> Self

Converts to this type from the input type.

impl From<Result<(), TryLockMutexError>> for ResultCode

fn from(x: Result<(), TryLockMutexError>) -> Self

Converts to this type from the input type.

impl From<Result<(), UnlockMutexError>> for ResultCode

fn from(x: Result<(), UnlockMutexError>) -> Self

Converts to this type from the input type.

impl From<Result<(), UnparkError>> for ResultCode

fn from(x: Result<(), UnparkError>) -> Self

Converts to this type from the input type.

impl From<Result<(), UnparkExactError>> for ResultCode

fn from(x: Result<(), UnparkExactError>) -> Self

Converts to this type from the input type.

impl From<Result<(), UpdateEventGroupError>> for ResultCode

fn from(x: Result<(), UpdateEventGroupError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitError>> for ResultCode

fn from(x: Result<(), WaitError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitEventGroupError>> for ResultCode

fn from(x: Result<(), WaitEventGroupError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitEventGroupTimeoutError>> for ResultCode

fn from(x: Result<(), WaitEventGroupTimeoutError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitSemaphoreError>> for ResultCode

fn from(x: Result<(), WaitSemaphoreError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitSemaphoreTimeoutError>> for ResultCode

fn from(x: Result<(), WaitSemaphoreTimeoutError>) -> Self

Converts to this type from the input type.

impl From<Result<(), WaitTimeoutError>> for ResultCode

fn from(x: Result<(), WaitTimeoutError>) -> Self

Converts to this type from the input type.

impl From<SetInterruptLinePriorityError> for ResultCode

fn from(x: SetInterruptLinePriorityError) -> Self

Converts to this type from the input type.

impl From<SetTaskPriorityError> for ResultCode

fn from(x: SetTaskPriorityError) -> Self

Converts to this type from the input type.

impl From<SetTimerDelayError> for ResultCode

fn from(x: SetTimerDelayError) -> Self

Converts to this type from the input type.

impl From<SetTimerPeriodError> for ResultCode

fn from(x: SetTimerPeriodError) -> Self

Converts to this type from the input type.

impl From<SignalSemaphoreError> for ResultCode

fn from(x: SignalSemaphoreError) -> Self

Converts to this type from the input type.

impl From<SleepError> for ResultCode

fn from(x: SleepError) -> Self

Converts to this type from the input type.

impl From<StartTimerError> for ResultCode

fn from(x: StartTimerError) -> Self

Converts to this type from the input type.

impl From<StopTimerError> for ResultCode

fn from(x: StopTimerError) -> Self

Converts to this type from the input type.

impl From<TimeError> for ResultCode

fn from(x: TimeError) -> Self

Converts to this type from the input type.

impl From<TryLockMutexError> for ResultCode

fn from(x: TryLockMutexError) -> Self

Converts to this type from the input type.

impl From<UnlockMutexError> for ResultCode

fn from(x: UnlockMutexError) -> Self

Converts to this type from the input type.

impl From<UnparkError> for ResultCode

fn from(x: UnparkError) -> Self

Converts to this type from the input type.

impl From<UnparkExactError> for ResultCode

fn from(x: UnparkExactError) -> Self

Converts to this type from the input type.

impl From<UpdateEventGroupError> for ResultCode

fn from(x: UpdateEventGroupError) -> Self

Converts to this type from the input type.

impl From<WaitError> for ResultCode

fn from(x: WaitError) -> Self

Converts to this type from the input type.

impl From<WaitEventGroupError> for ResultCode

fn from(x: WaitEventGroupError) -> Self

Converts to this type from the input type.

impl From<WaitEventGroupTimeoutError> for ResultCode

fn from(x: WaitEventGroupTimeoutError) -> Self

Converts to this type from the input type.

impl From<WaitSemaphoreError> for ResultCode

fn from(x: WaitSemaphoreError) -> Self

Converts to this type from the input type.

impl From<WaitSemaphoreTimeoutError> for ResultCode

fn from(x: WaitSemaphoreTimeoutError) -> Self

Converts to this type from the input type.

impl From<WaitTimeoutError> for ResultCode

fn from(x: WaitTimeoutError) -> Self

Converts to this type from the input type.

impl Hash for ResultCode

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, 

Feeds a slice of this type into the given Hasher.

impl Ord for ResultCode

fn cmp(&self, other: &ResultCode) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl PartialEq<ResultCode> for ResultCode

fn eq(&self, other: &ResultCode) -> 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 !=.

impl PartialOrd<ResultCode> for ResultCode

fn partial_cmp(&self, other: &ResultCode) -> 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 Copy for ResultCode

impl Eq for ResultCode

impl StructuralEq for ResultCode

impl StructuralPartialEq for ResultCode