Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document helper macros #365

Merged
merged 1 commit into from
Nov 20, 2023
Merged

Document helper macros #365

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,22 @@ and forth across the FFI boundary.

[Dynamically Sized Types]: https://doc.rust-lang.org/beta/reference/dynamically-sized-types.html
[trait objects]: https://doc.rust-lang.org/beta/reference/types/trait-object.html

# Helper macros

We have an API guideline that we always check input pointers for `NULL`, and
return an error or default value rather than dereferencing a `NULL` pointer.
To help with that, we have a number of helper macros that early-return if a
pointer is `NULL`:

- `try_ref_from_ptr!`
- `try_mut_from_ptr!`
- `try_box_from_ptr!`
- `try_clone_arc!`
- `try_callback!`
- `try_slice!`
- `try_take!`

These are defined in [src/lib.rs](src/lib.rs). The `Castable` trait determines which
C pointers can be cast to which Rust pointer types. These macros rely
on that trait to ensure correct typing of conversions.