@@ -116,6 +116,22 @@ pub struct File {
116116 inner : fs_imp:: File ,
117117}
118118
119+ /// An enumeration of possible errors which can occur while trying to acquire a lock
120+ /// from the [`try_lock`] method and [`try_lock_shared`] method on a [`File`].
121+ ///
122+ /// [`try_lock`]: File::try_lock
123+ /// [`try_lock_shared`]: File::try_lock_shared
124+ #[ unstable( feature = "file_lock" , issue = "130994" ) ]
125+ pub enum TryLockError {
126+ /// The lock could not be acquired due to an I/O error on the file. The standard library will
127+ /// not return an [`ErrorKind::WouldBlock`] error inside [`TryLockError::Error`]
128+ ///
129+ /// [`ErrorKind::WouldBlock`]: io::ErrorKind::WouldBlock
130+ Error ( io:: Error ) ,
131+ /// The lock could not be acquired at this time because it is held by another handle/process.
132+ WouldBlock ,
133+ }
134+
119135/// Metadata information about a file.
120136///
121137/// This structure is returned from the [`metadata`] or
@@ -352,6 +368,27 @@ pub fn write<P: AsRef<Path>, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result
352368 inner ( path. as_ref ( ) , contents. as_ref ( ) )
353369}
354370
371+ #[ unstable( feature = "file_lock" , issue = "130994" ) ]
372+ impl fmt:: Debug for TryLockError {
373+ fn fmt ( & self , f : & mut fmt:: Formatter < ' _ > ) -> fmt:: Result {
374+ match self {
375+ TryLockError :: Error ( err) => err. fmt ( f) ,
376+ TryLockError :: WouldBlock => "WouldBlock" . fmt ( f) ,
377+ }
378+ }
379+ }
380+
381+ #[ unstable( feature = "file_lock" , issue = "130994" ) ]
382+ impl fmt:: Display for TryLockError {
383+ fn fmt ( & self , f : & mut fmt:: Formatter < ' _ > ) -> fmt:: Result {
384+ match self {
385+ TryLockError :: Error ( _) => "lock acquisition failed due to I/O error" ,
386+ TryLockError :: WouldBlock => "lock acquisition failed because the operation would block" ,
387+ }
388+ . fmt ( f)
389+ }
390+ }
391+
355392impl File {
356393 /// Attempts to open a file in read-only mode.
357394///
@@ -734,8 +771,8 @@ impl File {
734771
735772 /// Try to acquire an exclusive lock on the file.
736773///
737- /// Returns `Ok(false )` if a different lock is already held on this file (via another
738- /// handle/descriptor).
774+ /// Returns `Err(TryLockError::WouldBlock )` if a different lock is already held on this file
775+ /// (via another handle/descriptor).
739776///
740777/// This acquires an exclusive lock; no other file handle to this file may acquire another lock.
741778///
@@ -777,23 +814,27 @@ impl File {
777814///
778815/// ```no_run
779816/// #![feature(file_lock)]
780- /// use std::fs::File;
817+ /// use std::fs::{ File, TryLockError} ;
781818///
782819/// fn main() -> std::io::Result<()> {
783820/// let f = File::create("foo.txt")?;
784- /// f.try_lock()?;
821+ /// match f.try_lock() {
822+ /// Ok(_) => (),
823+ /// Err(TryLockError::WouldBlock) => (), // Lock not acquired
824+ /// Err(TryLockError::Error(err)) => return Err(err),
825+ /// }
785826/// Ok(())
786827/// }
787828/// ```
788829#[ unstable( feature = "file_lock" , issue = "130994" ) ]
789- pub fn try_lock ( & self ) -> io :: Result < bool > {
830+ pub fn try_lock ( & self ) -> Result < ( ) , TryLockError > {
790831 self . inner . try_lock ( )
791832 }
792833
793834 /// Try to acquire a shared (non-exclusive) lock on the file.
794835///
795- /// Returns `Ok(false )` if an exclusive lock is already held on this file (via another
796- /// handle/descriptor).
836+ /// Returns `Err(TryLockError::WouldBlock )` if a different lock is already held on this file
837+ /// (via another handle/descriptor).
797838///
798839/// This acquires a shared lock; more than one file handle may hold a shared lock, but none may
799840/// hold an exclusive lock at the same time.
@@ -834,16 +875,21 @@ impl File {
834875///
835876/// ```no_run
836877/// #![feature(file_lock)]
837- /// use std::fs::File;
878+ /// use std::fs::{ File, TryLockError} ;
838879///
839880/// fn main() -> std::io::Result<()> {
840881/// let f = File::open("foo.txt")?;
841- /// f.try_lock_shared()?;
882+ /// match f.try_lock_shared() {
883+ /// Ok(_) => (),
884+ /// Err(TryLockError::WouldBlock) => (), // Lock not acquired
885+ /// Err(TryLockError::Error(err)) => return Err(err),
886+ /// }
887+ ///
842888/// Ok(())
843889/// }
844890/// ```
845891#[ unstable( feature = "file_lock" , issue = "130994" ) ]
846- pub fn try_lock_shared ( & self ) -> io :: Result < bool > {
892+ pub fn try_lock_shared ( & self ) -> Result < ( ) , TryLockError > {
847893 self . inner . try_lock_shared ( )
848894 }
849895
0 commit comments