enum Rav1dError: rename fields to more Rusty versions and add docs (#1442)

Pulled out the `Rav1dError` changes from #1439 into a separate PR.

Author: kkysen

src/data.rs

@@ -5,8 +5,7 @@ use std::ptr::NonNull;
 
 use crate::c_arc::CArc;
 use crate::c_box::{CBox, FnFree, Free};
-use crate::error::Rav1dError::EINVAL;
-use crate::error::Rav1dResult;
+use crate::error::{Rav1dError, Rav1dResult};
 use crate::include::common::validate::validate_input;
 use crate::include::dav1d::common::Rav1dDataProps;
 use crate::include::dav1d::data::Rav1dData;
@@ -39,7 +38,7 @@ impl Rav1dData {
         free_callback: Option<FnFree>,
         cookie: Option<SendSyncNonNull<c_void>>,
     ) -> Rav1dResult<Self> {
-        let free = validate_input!(free_callback.ok_or(EINVAL))?;
+        let free = validate_input!(free_callback.ok_or(Rav1dError::InvalidArgument))?;
         let free = Free { free, cookie };
         // SAFETY: Preconditions delegate to `CBox::from_c`'s safety.
         let data = unsafe { CBox::from_c(data, free) };
@@ -56,7 +55,7 @@ impl Rav1dData {
         free_callback: Option<FnFree>,
         cookie: Option<SendSyncNonNull<c_void>>,
     ) -> Rav1dResult {
-        let free = validate_input!(free_callback.ok_or(EINVAL))?;
+        let free = validate_input!(free_callback.ok_or(Rav1dError::InvalidArgument))?;
         let free = Free { free, cookie };
         // SAFETY: Preconditions delegate to `CBox::from_c`'s safety.
         let user_data = unsafe { CBox::from_c(user_data, free) };

src/decode.rs

@@ -22,8 +22,7 @@ use crate::env::{
     get_cur_frame_segid, get_drl_context, get_filter_ctx, get_gmv_2d, get_intra_ctx,
     get_jnt_comp_ctx, get_mask_comp_ctx, get_partition_ctx, get_poc_diff, get_tx_ctx, BlockContext,
 };
-use crate::error::Rav1dError::{EINVAL, ENOPROTOOPT};
-use crate::error::Rav1dResult;
+use crate::error::{Rav1dError, Rav1dResult};
 use crate::extensions::OptionError as _;
 use crate::include::common::attributes::ctz;
 use crate::include::common::bitdepth::BPC;
@@ -4594,7 +4593,7 @@ pub(crate) fn rav1d_decode_frame_init_cdf(
                 data.len()
             } else {
                 if n_bytes > data.len() {
-                    return Err(EINVAL);
+                    return Err(Rav1dError::InvalidArgument);
                 }
                 let (cur_data, rest_data) = CArc::split_at(data, n_bytes);
                 let tile_sz = cur_data
@@ -4605,7 +4604,7 @@ pub(crate) fn rav1d_decode_frame_init_cdf(
                     + 1;
                 data = rest_data;
                 if tile_sz > data.len() {
-                    return Err(EINVAL);
+                    return Err(Rav1dError::InvalidArgument);
                 }
                 tile_sz
             };
@@ -4709,7 +4708,7 @@ fn rav1d_decode_frame_main(c: &Rav1dContext, f: &mut Rav1dFrameData) -> Rav1dRes
             }
             for col in 0..cols {
                 t.ts = tile_row * cols + col;
-                rav1d_decode_tile_sbrow(c, &mut t, f).map_err(|()| EINVAL)?;
+                rav1d_decode_tile_sbrow(c, &mut t, f).map_err(|()| Rav1dError::InvalidArgument)?;
             }
             if f.frame_hdr().frame_type.is_inter_or_switch() {
                 c.dsp
@@ -4748,7 +4747,7 @@ pub(crate) fn rav1d_decode_frame_exit(
             rf.p.frame_hdr.is_some()
                 && rf.progress.as_ref().unwrap()[1].load(Ordering::SeqCst) == FRAME_ERROR
         }) {
-            retval = Err(EINVAL);
+            retval = Err(Rav1dError::InvalidArgument);
             task_thread.error.store(1, Ordering::SeqCst);
             f.sr_cur.progress.as_mut().unwrap()[1].store(FRAME_ERROR, Ordering::SeqCst);
         }
@@ -4932,7 +4931,7 @@ pub fn rav1d_submit_frame(c: &Rav1dContext, state: &mut Rav1dState) -> Rav1dResu
                 &mut state.cached_error_props,
                 &state.in_0.m,
             );
-            return Err(ENOPROTOOPT);
+            return Err(Rav1dError::UnsupportedBitstream);
         }
     };
 
@@ -4953,7 +4952,7 @@ pub fn rav1d_submit_frame(c: &Rav1dContext, state: &mut Rav1dState) -> Rav1dResu
                     &mut state.cached_error_props,
                     &state.in_0.m,
                 );
-                return Err(EINVAL);
+                return Err(Rav1dError::InvalidArgument);
             }
         }
         for i in 0..7 {
@@ -4976,7 +4975,7 @@ pub fn rav1d_submit_frame(c: &Rav1dContext, state: &mut Rav1dState) -> Rav1dResu
                     &mut state.cached_error_props,
                     &state.in_0.m,
                 );
-                return Err(EINVAL);
+                return Err(Rav1dError::InvalidArgument);
             }
             f.refp[i] = state.refs[refidx].p.clone();
             ref_coded_width[i] = state.refs[refidx]

src/error.rs

@@ -1,31 +1,82 @@
+use std::error::Error;
 use std::ffi::{c_int, c_uint};
+use std::fmt::{self, Display, Formatter};
 
 use strum::FromRepr;
 
+/// Error enum return by various `rav1d` operations.
 #[derive(Clone, Copy, PartialEq, Eq, FromRepr, Debug)]
 #[repr(u8)]
 #[non_exhaustive]
 pub enum Rav1dError {
     /// This represents a generic `rav1d` error.
-    /// It has nothing to do with the other `errno`-based ones
-    /// (and that's why it's not all caps like the other ones).
+    /// It has nothing to do with the other `errno`-based ones.
     ///
     /// Normally `EPERM = 1`, but `dav1d` never uses `EPERM`,
     /// but does use `-1`, as opposed to the normal `DAV1D_ERR(E*)`.
     ///
-    /// Also Note that this forces `0` to be the niche,
+    /// Also note that this forces `0` to be the niche,
     /// which is more optimal since `0` is no error for [`Dav1dResult`].
-    EGeneric = 1,
-
-    ENOENT = libc::ENOENT as u8,
-    EIO = libc::EIO as u8,
-    EAGAIN = libc::EAGAIN as u8,
-    ENOMEM = libc::ENOMEM as u8,
-    EINVAL = libc::EINVAL as u8,
-    ERANGE = libc::ERANGE as u8,
-    ENOPROTOOPT = libc::ENOPROTOOPT as u8,
+    Other = 1,
+
+    /// No entity.
+    ///
+    /// No Sequence Header OBUs were found in the buffer.
+    NoEntity = libc::ENOENT as u8,
+
+    /// Try again.
+    ///
+    /// If this is returned by [`rav1d_send_data`], then there
+    /// are decoded frames pending that first have to be retrieved via [`rav1d_get_picture`]
+    /// before processing any further pending data.
+    ///
+    /// If this is returned by [`rav1d_get_picture`], then no decoded frames are pending
+    /// currently and more data needs to be sent to the decoder.
+    TryAgain = libc::EAGAIN as u8,
+
+    /// Out of memory.
+    ///
+    /// Not enough memory is currently available for performing this operation.
+    OutOfMemory = libc::ENOMEM as u8,
+
+    /// Invalid argument.
+    ///
+    /// One of the arguments passed to the function, including the bitstream, is invalid.
+    InvalidArgument = libc::EINVAL as u8,
+
+    /// Out of range.
+    ///
+    /// The frame size is larger than the limit.
+    OutOfRange = libc::ERANGE as u8,
+
+    /// Unsupported bitstream.
+    ///
+    /// The provided bitstream is not supported by `rav1d`.
+    UnsupportedBitstream = libc::ENOPROTOOPT as u8,
+}
+
+impl Rav1dError {
+    pub const fn as_str(&self) -> &'static str {
+        match self {
+            Rav1dError::TryAgain => "Try again",
+            Rav1dError::InvalidArgument => "Invalid argument",
+            Rav1dError::OutOfMemory => "Not enough memory available",
+            Rav1dError::UnsupportedBitstream => "Unsupported bitstream",
+            Rav1dError::Other => "Other error",
+            Rav1dError::NoEntity => "No sequence header found",
+            Rav1dError::OutOfRange => "Out of range",
+        }
+    }
 }
 
+impl Display for Rav1dError {
+    fn fmt(&self, fmt: &mut Formatter) -> fmt::Result {
+        write!(fmt, "{}", self.as_str())
+    }
+}
+
+impl Error for Rav1dError {}
+
 pub type Rav1dResult<T = ()> = Result<T, Rav1dError>;
 
 #[derive(Clone, Copy, PartialEq, Eq, Debug)]

src/include/dav1d/dav1d.rs

@@ -80,7 +80,7 @@ impl TryFrom<Dav1dDecodeFrameType> for Rav1dDecodeFrameType {
     type Error = Rav1dError;
 
     fn try_from(value: Dav1dDecodeFrameType) -> Result<Self, Self::Error> {
-        Self::from_repr(value as usize).ok_or(Rav1dError::EINVAL)
+        Self::from_repr(value as usize).ok_or(Rav1dError::InvalidArgument)
     }
 }
 

src/include/dav1d/picture.rs

@@ -14,7 +14,6 @@ use crate::c_arc::RawArc;
 use crate::disjoint_mut::{
     AsMutPtr, DisjointImmutGuard, DisjointMut, DisjointMutGuard, SliceBounds,
 };
-use crate::error::Rav1dError::EINVAL;
 use crate::error::{Dav1dResult, Rav1dError, Rav1dResult};
 use crate::ffi_safe::FFISafe;
 use crate::include::common::bitdepth::BitDepth;
@@ -719,8 +718,12 @@ impl TryFrom<Dav1dPicAllocator> for Rav1dPicAllocator {
         } = value;
         Ok(Self {
             cookie,
-            alloc_picture_callback: validate_input!(alloc_picture_callback.ok_or(EINVAL))?,
-            release_picture_callback: validate_input!(release_picture_callback.ok_or(EINVAL))?,
+            alloc_picture_callback: validate_input!(
+                alloc_picture_callback.ok_or(Rav1dError::InvalidArgument)
+            )?,
+            release_picture_callback: validate_input!(
+                release_picture_callback.ok_or(Rav1dError::InvalidArgument)
+            )?,
         })
     }
 }