Skip to content

Commit

Permalink
docs: add more intra-doc links
Browse files Browse the repository at this point in the history
  • Loading branch information
@weihanglo @petrochenkov
weihanglo authored and petrochenkov committed Mar 4, 2024
1 parent 5530ff4 commit 2059bac
Show file tree
Hide file tree
Showing 2 changed files with 54 additions and 49 deletions.
8 changes: 6 additions & 2 deletions src/error.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,17 @@ type RawFd = std::os::unix::io::RawFd;
#[cfg(not(unix))]
type RawFd = std::convert::Infallible;

/// Error type for `from_env_ext` function.
/// Error type for [`Client::from_env_ext`] function.
///
/// [`Client::from_env_ext`]: crate::Client::from_env_ext
#[derive(Debug)]
pub struct FromEnvError {
pub(crate) inner: FromEnvErrorInner,
}

/// Kind of an error returned from `from_env_ext` function.
/// Kind of an error returned from [`Client::from_env_ext`] function.
///
/// [`Client::from_env_ext`]: crate::Client::from_env_ext
#[derive(Debug)]
#[non_exhaustive]
pub enum FromEnvErrorKind {
Expand Down
95 changes: 48 additions & 47 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,8 +109,8 @@ mod imp;
/// Some usage examples can be found in the crate documentation for using a
/// client.
///
/// Note that a `Client` implements the `Clone` trait, and all instances of a
/// `Client` refer to the same jobserver instance.
/// Note that a [`Client`] implements the [`Clone`] trait, and all instances of
/// a [`Client`] refer to the same jobserver instance.
#[derive(Clone, Debug)]
pub struct Client {
inner: Arc<imp::Client>,
Expand All @@ -128,13 +128,13 @@ pub struct Acquired {
}

impl Acquired {
/// This drops the `Acquired` token without releasing the associated token.
/// This drops the [`Acquired`] token without releasing the associated token.
///
/// This is not generally useful, but can be helpful if you do not have the
/// ability to store an Acquired token but need to not yet release it.
///
/// You'll typically want to follow this up with a call to `release_raw` or
/// similar to actually release the token later on.
/// You'll typically want to follow this up with a call to
/// [`Client::release_raw`] or similar to actually release the token later on.
pub fn drop_without_releasing(mut self) {
self.disabled = true;
}
Expand All @@ -156,7 +156,7 @@ struct HelperInner {
use error::FromEnvErrorInner;
pub use error::{FromEnvError, FromEnvErrorKind};

/// Return type for `from_env_ext` function.
/// Return type for [`Client::from_env_ext`] function.
#[derive(Debug)]
pub struct FromEnv {
/// Result of trying to get jobserver client from env.
Expand Down Expand Up @@ -186,12 +186,12 @@ impl Client {
///
/// A client to the jobserver created will be returned. This client will
/// allow at most `limit` tokens to be acquired from it in parallel. More
/// calls to `acquire` will cause the calling thread to block.
/// calls to [`Client::acquire`] will cause the calling thread to block.
///
/// Note that the created `Client` is not automatically inherited into
/// Note that the created [`Client`] is not automatically inherited into
/// spawned child processes from this program. Manual usage of the
/// `configure` function is required for a child process to have access to a
/// job server.
/// [`Client::configure`] function is required for a child process to have
/// access to a job server.
///
/// # Examples
///
Expand Down Expand Up @@ -219,14 +219,14 @@ impl Client {
/// it's passing down. This function will attempt to look for these details
/// and connect to the jobserver.
///
/// Note that the created `Client` is not automatically inherited into
/// Note that the created [`Client`] is not automatically inherited into
/// spawned child processes from this program. Manual usage of the
/// `configure` function is required for a child process to have access to a
/// job server.
/// [`Client::configure`] function is required for a child process to have
/// access to a job server.
///
/// # Return value
///
/// `FromEnv` contains result and relevant environment variable.
/// [`FromEnv`] contains result and relevant environment variable.
/// If a jobserver was found in the environment and it looks correct then
/// result with the connected client will be returned. In other cases
/// result will contain `Err(FromEnvErr)`.
Expand Down Expand Up @@ -281,7 +281,7 @@ impl Client {
/// Attempts to connect to the jobserver specified in this process's
/// environment.
///
/// Wraps `from_env_ext` and discards error details.
/// Wraps [`Client::from_env_ext`] and discards error details.
///
/// # Safety
///
Expand All @@ -306,7 +306,7 @@ impl Client {
///
/// # Return value
///
/// On successful acquisition of a token an instance of `Acquired` is
/// On successful acquisition of a token an instance of [`Acquired`] is
/// returned. This structure, when dropped, will release the token back to
/// the jobserver. It's recommended to avoid leaking this value.
///
Expand Down Expand Up @@ -342,9 +342,10 @@ impl Client {
///
/// This function is required to be called to ensure that a jobserver is
/// properly inherited to a child process. If this function is *not* called
/// then this `Client` will not be accessible in the child process. In other
/// words, if not called, then `Client::from_env` will return `None` in the
/// child process (or the equivalent of `Child::from_env` that `make` uses).
/// then this [`Client`] will not be accessible in the child process. In
/// other words, if not called, then [`Client::from_env`] will return `None`
/// in the child process (or the equivalent of [`Client::from_env`] that
/// `make` uses).
///
/// ## Platform-specific behavior
///
Expand All @@ -363,9 +364,10 @@ impl Client {
///
/// This function is required to be called to ensure that a jobserver is
/// properly inherited to a child process. If this function is *not* called
/// then this `Client` will not be accessible in the child process. In other
/// words, if not called, then `Client::from_env` will return `None` in the
/// child process (or the equivalent of `Child::from_env` that `make` uses).
/// then this [`Client`] will not be accessible in the child process. In
/// other words, if not called, then [`Client::from_env`] will return `None`
/// in the child process (or the equivalent of [`Client::from_env`] that
/// `make` uses).
///
/// ## Platform-specific behavior
///
Expand All @@ -391,19 +393,18 @@ impl Client {
format!("-j --jobserver-fds={0} --jobserver-auth={0}", arg)
}

/// Converts this `Client` into a helper thread to deal with a blocking
/// `acquire` function a little more easily.
/// Converts this [`Client`] into a helper thread to deal with a blocking
/// [`Client::acquire`] function a little more easily.
///
/// The fact that the `acquire` function on `Client` blocks isn't always
/// the easiest to work with. Typically you're using a jobserver to
/// manage running other events in parallel! This means that you need to
/// either (a) wait for an existing job to finish or (b) wait for a
/// new token to become available.
/// The fact that the [`Client::acquire`] isn't always the easiest to work
/// with. Typically you're using a jobserver to manage running other events
/// in parallel! This means that you need to either (a) wait for an existing
/// job to finish or (b) wait for a new token to become available.
///
/// Unfortunately the blocking in `acquire` happens at the implementation
/// layer of jobservers. On Unix this requires a blocking call to `read`
/// and on Windows this requires one of the `WaitFor*` functions. Both
/// of these situations aren't the easiest to deal with:
/// Unfortunately the blocking in [`Client::acquire`] happens at the
/// implementation layer of jobservers. On Unix this requires a blocking
/// call to `read` and on Windows this requires one of the `WaitFor*`
/// functions. Both of these situations aren't the easiest to deal with:
///
/// * On Unix there's basically only one way to wake up a `read` early, and
/// that's through a signal. This is what the `make` implementation
Expand All @@ -419,7 +420,7 @@ impl Client {
/// unfortunately.
///
/// This function essentially attempts to ease these limitations by
/// converting this `Client` into a helper thread spawned into this
/// converting this [`Client`] into a helper thread spawned into this
/// process. The application can then request that the helper thread
/// acquires tokens and the provided closure will be invoked for each token
/// acquired.
Expand All @@ -429,23 +430,23 @@ impl Client {
///
/// # Arguments
///
/// This function will consume the `Client` provided to be transferred to
/// This function will consume the [`Client`] provided to be transferred to
/// the helper thread that is spawned. Additionally a closure `f` is
/// provided to be invoked whenever a token is acquired.
///
/// This closure is only invoked after calls to
/// `HelperThread::request_token` have been made and a token itself has
/// [`HelperThread::request_token`] have been made and a token itself has
/// been acquired. If an error happens while acquiring the token then
/// an error will be yielded to the closure as well.
///
/// # Return Value
///
/// This function will return an instance of the `HelperThread` structure
/// This function will return an instance of the [`HelperThread`] structure
/// which is used to manage the helper thread associated with this client.
/// Through the `HelperThread` you'll request that tokens are acquired.
/// Through the [`HelperThread`] you'll request that tokens are acquired.
/// When acquired, the closure provided here is invoked.
///
/// When the `HelperThread` structure is returned it will be gracefully
/// When the [`HelperThread`] structure is returned it will be gracefully
/// torn down, and the calling thread will be blocked until the thread is
/// torn down (which should be prompt).
///
Expand Down Expand Up @@ -482,19 +483,19 @@ impl Client {

/// Blocks the current thread until a token is acquired.
///
/// This is the same as `acquire`, except that it doesn't return an RAII
/// helper. If successful the process will need to guarantee that
/// `release_raw` is called in the future.
/// This is the same as [`Client::acquire`], except that it doesn't return
/// an RAII helper. If successful the process will need to guarantee that
/// [`Client::release_raw`] is called in the future.
pub fn acquire_raw(&self) -> io::Result<()> {
self.inner.acquire()?;
Ok(())
}

/// Releases a jobserver token back to the original jobserver.
///
/// This is intended to be paired with `acquire_raw` if it was called, but
/// in some situations it could also be called to relinquish a process's
/// implicit token temporarily which is then re-acquired later.
/// This is intended to be paired with [`Client::acquire_raw`] if it was
/// called, but in some situations it could also be called to relinquish a
/// process's implicit token temporarily which is then re-acquired later.
pub fn release_raw(&self) -> io::Result<()> {
self.inner.release(None)?;
Ok(())
Expand All @@ -509,7 +510,7 @@ impl Drop for Acquired {
}
}

/// Structure returned from `Client::into_helper_thread` to manage the lifetime
/// Structure returned from [`Client::into_helper_thread`] to manage the lifetime
/// of the helper thread returned, see those associated docs for more info.
#[derive(Debug)]
pub struct HelperThread {
Expand All @@ -521,7 +522,7 @@ impl HelperThread {
/// Request that the helper thread acquires a token, eventually calling the
/// original closure with a token when it's available.
///
/// For more information, see the docs on that function.
/// For more information, see the docs on [`Client::into_helper_thread`].
pub fn request_token(&self) {
// Indicate that there's one more request for a token and then wake up
// the helper thread if it's sleeping.
Expand Down

0 comments on commit 2059bac

Please sign in to comment.