Skip to content

Commit

Permalink
doc: Improve documentation to make possibility of leaks more clear (#…
Browse files Browse the repository at this point in the history
  • Loading branch information
Byron committed Sep 21, 2023
1 parent 14e0763 commit a8b227e
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 3 deletions.
15 changes: 15 additions & 0 deletions gix-tempfile/src/handle.rs
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,11 @@ impl Handle<Closed> {
///
/// Depending on the `directory` configuration, intermediate directories will be created, and depending on `cleanup` empty
/// intermediate directories will be removed.
///
/// ### Warning of potential leaks
///
/// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
/// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
pub fn at(path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove) -> io::Result<Self> {
Ok(Handle {
id: Handle::<()>::at_path(path.as_ref(), directory, cleanup, Mode::Closed)?,
Expand All @@ -92,6 +97,11 @@ impl Handle<Writable> {
///
/// Depending on the `directory` configuration, intermediate directories will be created, and depending on `cleanup` empty
/// intermediate directories will be removed.
///
/// ### Warning of potential leaks
///
/// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
/// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
pub fn at(path: impl AsRef<Path>, directory: ContainingDirectory, cleanup: AutoRemove) -> io::Result<Self> {
Ok(Handle {
id: Handle::<()>::at_path(path.as_ref(), directory, cleanup, Mode::Writable)?,
Expand All @@ -102,6 +112,11 @@ impl Handle<Writable> {
/// Create a registered tempfile within `containing_directory` with a name that won't clash, and clean it up as specified with `cleanup`.
/// Control how to deal with intermediate directories with `directory`.
/// The temporary file is opened and can be written to using the [`with_mut()`][Handle::with_mut()] method.
///
/// ### Warning of potential leaks
///
/// Without [signal handlers](crate::signal) installed, tempfiles will remain once a termination
/// signal is encountered as destructors won't run. See [the top-level documentation](crate) for more.
pub fn new(
containing_directory: impl AsRef<Path>,
directory: ContainingDirectory,
Expand Down
7 changes: 4 additions & 3 deletions gix-tempfile/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@
//!
//! ### Initial Setup
//!
//! As no handlers for `TERMination` are installed, it is required to call [`signal::setup()`] before creating the first tempfile.
//! This also allows to control how `git-tempfiles` integrates with other handlers under application control.
//! As no handlers for `TERMination` are installed, it is required to call [`signal::setup()`] before creating
//! the first tempfile. This also allows to control how this crate integrates with
//! other handlers under application control.
//!
//! As a general rule of thumb, use `Default::default()` as argument to emulate the default behaviour and
//! abort the process after cleaning temporary files. Read more about options in [`signal::handler::Mode`].
Expand All @@ -23,7 +24,7 @@
//! * The application is performing a write operation on the tempfile when a signal arrives, preventing this tempfile to be removed,
//! but not others. Any other operation dealing with the tempfile suffers from the same issue.
//!
//! [signal-hook]: https://docs.rs/signal-hook
//! [`signal-hook`]: https://docs.rs/signal-hook
//!
//! ## Feature Flags
#![cfg_attr(
Expand Down

0 comments on commit a8b227e

Please sign in to comment.