sync::one::Once should be able to "ignore" a run

[huonw]

sync::one::Once is often used for one-time initialisation (e.g. of C libraries), but non-trivial initialisations take arguments and can fail, and in the failure case, one might wish to retry with different arguments.

E.g.

#[link(name="my_lib")];
extern {
     // negative return value indicates failure
     fn my_lib_init(x: u32) -> i32;
}
fn start_up(x: u32) -> i32 {
    static mut GUARD: Once = /* ... */;
    let mut ret = -1;
    GUARD.doit(|| {
        ret = my_lib_init(x);
    });
    ret
}

fn main() {
    // lets try with 0
    if start_up(0) >= 0 { main_app() }

    // that failed, maybe 1 will work
    else if start_up(1) >= 0 { main_app() }

    else { println!("failed to initialise") }
}

Unfortunately, that code is incorrect, because the second start_up call will never call my_lib_init: the first one consumed the guard.

One solution would be doit having signature fn doit(...) -> bool; with false indicating the code path "failed" and the Once should be allowed to rerun (i.e. no clean-up or anything). i.e. the current behaviour is when doit returns true.

(One could also add a new method try and make doit(f) just sugar for try(|| { f(); true }).)

[brendanzab]

Here is a use-case: PistonDevelopers/glfw-rs#132

[edwardw]

sync::one::Once uses a sync::mutex::StaticMutex internally as guard. One difficulty about a new fn try(...) -> bool is that it may never succeeded so the static guard may never be consumed. Is there some sort of global hook I can use to do the cleanup for that StaticMutex?

[huonw]

I guess that's a consideration, but I don't think it's a huge problem: if Once's closure "fails" every time, then it seems rather likely that the program is going to give up and exit relatively quickly (leaving the operating system to clean up anything about the mutexes that it needs to, which is perfectly valid).

[lilyball]

I disagree with this issue. Once is a very targeted API, intended for use-cases where 99.9% of calls do nothing. It's convenient for library initialization, but there are plenty of alternatives when you need different behavior, such as using a Mutex and a boolean variable. That replacement would not only have the same semantics as being asked for in this issue, but would have the same performance too (since we're considering a library initialization routine that's only invoked when the caller expects the library hasn't been initialized yet). And it can be done without changing any library API whatsoever.

[huonw]

I guess the following works, yeah.

use sync::mutex::{MUTEX_INIT, StaticMutex};

fn init(x: u32) -> i32 {
    static mut init_mutex: StaticMutex = MUTEX_INIT;
    static mut inited: bool = false;

    unsafe {
        let _guard = init_mutex.lock();
        if inited { return 0 }

        ret = my_lib_init(x);
        inited = ret >= 0;
        ret
    }
}

Closing. (If someone feels like this is insufficient, you can reopen/request a reopening.)

[brendanzab]

Could you have something like:

use sync::mutex::{MUTEX_INIT, StaticMutex};

pub struct TryOnce {
    mutex: StaticMutex,
    is_done: bool,
}

pub static TRY_ONCE_INIT: TryOnce = TryOnce {
    mutex: MUTEX_INIT,
    is_done: false,
};

impl TryOnce {
    /// Attempt to call `f`.
    ///
    /// # Arguments
    ///
    /// - `f`: A function that will only be called if `TryOnce::try` has not
    ///   previously been called successfully.
    ///   - To indicate that the function call was successful an `OK(_)` value
    ///     should be returned. This will prevent  all subsequent subsequent
    ///     calls to `TryOnce::try` from executing `f` and `Some(OK(_))` to be
    ///     returned.
    ///   - To indicate that the function call failed an `Err(_)` value should
    ///     be returned. This will allow `TryOnce::try` to be called again, and
    ///     will cause `TryOnce::try` to return `Some(Err(_))`.
    ///
    /// # Returns
    ///
    /// - `Some(_)` if `TryOnce::try` has never been successfully called.
    /// - `None` if `TryOnce::try` has previously returned `Some(Ok(_))`.
    ///
    /// # Example
    ///
    /// ~~~rust
    /// # mod ffi {
    /// #     pub static FALSE: int = 0;
    /// #     pub static TRUE:  int = 1;
    /// #     pub fn init() -> int { TRUE }
    /// # }
    ///
    /// enum InitError {
    ///     InternalInitError,
    ///     AlreadyInitialized,
    /// }
    ///
    /// fn init() -> Result<~str, InitError> {
    ///     static mut INIT: TryOnce = TRY_ONCE_INIT;
    ///     unsafe {
    ///         INIT.try(&|| {
    ///             if ffi::init() == ffi::TRUE {
    ///                 Ok(~"hi!")
    ///             } else {
    ///                 Err(InternalInitError)
    ///             }
    ///         })
    ///     }.unwrap_or(Err(AlreadyInitialized))
    /// }
    /// ~~~
    pub fn try<T, E>(&mut self, f: &|| -> Result<T, E>) -> Option<Result<T, E>> {
        let guard = self.mutex.lock();
        let result = if self.is_done {
            None
        } else {
            let result = (*f)();
            self.is_done = result.is_ok();
            Some(result)
        };
        drop(guard);
        result
    }
}

#[cfg(test)]
mod tests {
    use super::{TRY_ONCE_INIT, TryOnce};

    #[deriving(Eq, Show)]
    enum InitError {
        InternalInitError,
        AlreadyInitialized,
    }

    #[test]
    fn test() {
        static mut INIT: TryOnce = TRY_ONCE_INIT;

        let err: &|| -> Result<~str, InitError> = &|| Err(InternalInitError);
        let ok:  &|| -> Result<~str, InitError> = &|| Ok(~"pickles");

        assert_eq!(unsafe { INIT.try(err) }, Some(Err(InternalInitError)));
        assert_eq!(unsafe { INIT.try(ok)  }, Some(Ok(~"pickles")));
        assert_eq!(unsafe { INIT.try(err) }, None);
        assert_eq!(unsafe { INIT.try(ok)  }, None);
    }
}