Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
G
getrandom
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Package Registry
Container Registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Issue analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Terms and privacy
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
felixmoebius
getrandom
Commits
1ebd2ce0
Commit
1ebd2ce0
authored
4 years ago
by
Joe Richey
Committed by
Joseph Richey
4 years ago
Browse files
Options
Downloads
Patches
Plain Diff
docs: Clarify intended usage for Custom RNGs
Signed-off-by:
Joe Richey
<
joerichey@google.com
>
parent
a6fa63c6
No related branches found
Branches containing commit
No related tags found
Tags containing commit
No related merge requests found
Changes
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
src/custom.rs
+41
-15
41 additions, 15 deletions
src/custom.rs
src/lib.rs
+9
-22
9 additions, 22 deletions
src/lib.rs
with
50 additions
and
37 deletions
src/custom.rs
+
41
−
15
View file @
1ebd2ce0
...
...
@@ -12,40 +12,66 @@ use core::num::NonZeroU32;
/// Register a function to be invoked by `getrandom` on unsupported targets.
///
/// *This API requires the
following
Cargo feature
s
to be activated
: `"custom"`
*
/// *This API requires the
`"custom"`
Cargo feature to be activated*
.
///
/// ## Writing
your own
custom `getrandom` implementation
/// ## Writing
a
custom `getrandom` implementation
///
///
Users can define custom implementations either in their root crate or in
a
///
target specific helper-crate. We will use the helper-crate approach in this
///
example, defining `dummy-getrandom`, an implementation that always fails
.
///
The function to register must have the same signature
a
s
///
[`getrandom::getrandom`](crate::getrandom). The function can be defined
///
wherever you want, either in root crate or a dependant crate
.
///
/// First, in `dummy-getrandom/Cargo.toml` we depend on `getrandom`:
/// For example, if we wanted a `failure-getrandom` crate containing an
/// implementation that always fails, we would first depend on `getrandom`
/// (for the [`Error`] type) in `failure-getrandom/Cargo.toml`:
/// ```toml
/// [dependencies]
/// getrandom =
{ version = "0.2", features = ["custom"] }
/// getrandom =
"0.2"
/// ```
/// Note that the crate containing this function does **not** need to enable the
/// `"custom"` Cargo feature.
///
/// Next, in `
dummy
-getrandom/src/lib.rs`, we define our
custom implementation and register it
:
/// Next, in `
failure
-getrandom/src/lib.rs`, we define our
function
:
/// ```rust
/// use core::num::NonZeroU32;
/// use getrandom::
{
Error
, register_custom_getrandom}
;
/// use getrandom::Error;
///
/// // Some application-specific error code
/// const MY_CUSTOM_ERROR_CODE: u32 = Error::CUSTOM_START + 42;
/// fn always_fail(buf: &mut [u8]) -> Result<(), Error> {
///
pub
fn always_fail(buf: &mut [u8]) -> Result<(), Error> {
/// let code = NonZeroU32::new(MY_CUSTOM_ERROR_CODE).unwrap();
/// Err(Error::from(code))
/// }
/// ```
///
/// ## Registering a custom `getrandom` implementation
///
/// Functions can only be registered in the root binary crate. Attempting to
/// register a function in a non-root crate will result in a linker error.
/// This is similar to
/// [`#[panic_handler]`](https://doc.rust-lang.org/nomicon/panic-handler.html) or
/// [`#[global_allocator]`](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/global-allocators.html),
/// where helper crates define handlers/allocators but only the binary crate
/// actually _uses_ the functionality.
///
/// To register the function, we first depend on `getrandom` in `Cargo.toml`:
/// ```toml
/// [dependencies]
/// getrandom = { version = "0.2", features = ["custom"] }
/// ```
///
/// Then, we register the function in `src/main.rs`:
/// ```rust
/// # mod failure_getrandom { pub fn always_fail(_: &mut [u8]) -> Result<(), getrandom::Error> { unimplemented!() } }
/// use failure_getrandom::always_fail;
/// use getrandom::register_custom_getrandom;
///
/// register_custom_getrandom!(always_fail);
/// ```
/// the registered function must have the same type signature as
/// [`getrandom::getrandom`](crate::getrandom).
///
/// Now any user of `getrandom` (direct or indirect) on this target will use the
///
above custom implementation. See
the
/// [
usage
documentation](index.html#use-a-custom-implementation)
for information about
///
_using_ such a custom implementation
.
///
registered function. As noted in
the
/// [
top-level
documentation](index.html#use-a-custom-implementation)
this
///
registration only has an effect on unsupported targets
.
#[macro_export]
macro_rules!
register_custom_getrandom
{
(
$path:path
)
=>
{
...
...
This diff is collapsed.
Click to expand it.
src/lib.rs
+
9
−
22
View file @
1ebd2ce0
...
...
@@ -75,30 +75,17 @@
//!
//! This feature has no effect on targets other than `wasm32-unknown-unknown`.
//!
//! ###
Use a c
ustom implementation
//! ###
C
ustom implementation
s
//!
//!
Some external crates define `getrandom` implementations for specific
//! un
supported targets. If you depend on one of these external crates and you
//!
are building for an unsupported target, `getrandom` will use this external
//! implementation
instead of failing to compile
.
//!
The [`register_custom_getrandom!`] macro allows a user to mark their own
//!
f
un
ction as the backing implementation for [`getrandom`]. See the macro's
//!
documentation for more information about writing and registering your own
//!
custom
implementation
s
.
//!
//! Using such an external implementation requires depending on it in your
//! `Cargo.toml` _and_ using it in your binary crate with:
//! ```ignore
//! use some_custom_getrandom_crate;
//! ```
//! (failure to do this will cause linker errors).
//!
//! Other than [dev-dependencies](https://doc.rust-lang.org/stable/rust-by-example/testing/dev_dependencies.html),
//! library crates should **not** depend on external implementation crates.
//! Only binary crates should depend/use such crates. This is similar to
//! [`#[panic_handler]`](https://doc.rust-lang.org/nomicon/panic-handler.html) or
//! [`#[global_allocator]`](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/global-allocators.html),
//! where helper crates define handlers/allocators but only the binary crate
//! actually _uses_ the functionality.
//!
//! See [`register_custom_getrandom!`] for information about writing your own
//! custom `getrandom` implementation for an unsupported target.
//! Note that registering a custom implementation only has an effect on targets
//! that would otherwise not compile. Any supported targets (including those
//! using `"rdrand"` and `"js"` Cargo features) continue using their normal
//! implementations even if a function is registered.
//!
//! ### Indirect Dependencies
//!
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment