Skip to content

error-handling.md

Latest commit

 

History

History
138 lines (113 loc) · 4.94 KB

error-handling.md

File metadata and controls

138 lines (113 loc) · 4.94 KB
Raw

Error handling

rust-samp follows Rust's Result convention for error reporting, with a single error type for every AMX VM failure.

AmxResult<T>

pub type AmxResult<T> = Result<T, AmxError>;

Most SDK methods return AmxResult<T>. A native can return either AmxResult<T> (or any Result<T, E: Display>) — in which case the generated wrapper logs the Err and returns 0 — or a bare T that implements AmxCell.

#[native(name = "Divide")]
fn divide(&mut self, _amx: &Amx, a: i32, b: i32) -> AmxResult<i32> {
    if b == 0 {
        return Err(AmxError::Divide); // division by zero
    }
    Ok(a / b)
}

AmxError

AmxError mirrors the codes defined by the AMX C header. Built via AmxError::from(code) from any i32; unknown values become AmxError::Unknown instead of panicking.

Variant Code Display
Exit 1 Forced exit
Assert 2 Assertion failed
StackError 3 Stack / heap collision
Bounds 4 Index out of bounds
MemoryAccess 5 Invalid memory access
InvalidInstruction 6 Invalid instruction
StackLow 7 Stack underflow
HeapLow 8 Heap underflow
Callback 9 No callback or invalid callback
Native 10 Native function failed
Divide 11 Divide by zero
Sleep 12 Go into sleepmode
InvalidState 13 No implementation for this state, no fall-back
Memory 16 Out of memory
Format 17 Invalid file format
Version 18 File is for a newer version of AMX
NotFound 19 Function not found
Index 20 Invalid index parameter (bad entry point)
Debug 21 Debugger cannot run
Init 22 AMX not initialize
UserData 23 Unable to set user data field
InitJit 24 Cannot initialize the JIT
Params 25 Parameter error
Domain 26 Domain error, expression result does not fit in range
General 27 General error (unknown or unspecific error)
Overlay 28 Overlays are unsupported (JIT) or uninitialized
Unknown — Unknown error

AmxError implements std::error::Error, so it composes with ?, anyhow, eyre, and friends.

Propagation with ?

#[native(name = "CallCallback")]
fn call_callback(&mut self, amx: &Amx) -> AmxResult<bool> {
    let index  = amx.find_public("OnMyCallback")?;
    let result = amx.exec(index)?;
    Ok(result > 0)
}

Converting from i32

let err  = AmxError::from(19);   // AmxError::NotFound
let code = AmxError::NotFound as i32; // 19

Display

Every variant has a stable, English message that maps 1:1 to the original C header strings:

let err = AmxError::NotFound;
println!("{err}"); // "Function not found"

Common patterns

Reporting status to Pawn through the return value

Sometimes it is more convenient to return a status code from the native than to log an error:

#[native(name = "TryConnect")]
fn try_connect(&mut self, _amx: &Amx, address: &AmxString) -> i32 {
    match self.connect(&**address) {
        Ok(_)  => 1,
        Err(_) => -1,
    }
}

Custom return type implementing AmxCell

When several outcomes share the same native, a small enum + AmxCell keeps the call sites readable:

#[derive(Clone, Copy)]
enum Status {
    Ok,
    NotFound,
    Error,
}

impl AmxCell<'_> for Status {
    fn as_cell(&self) -> i32 {
        match self {
            Status::Ok       => 1,
            Status::NotFound => 0,
            Status::Error    => -1,
        }
    }
}

#[native(name = "DoSomething")]
fn do_something(&mut self, _amx: &Amx) -> Status {
    Status::Ok
}