golang.org/x/tools@v0.21.1-0.20240520172518-788d39e776b1/internal/robustio/robustio.go (about)

     1  // Copyright 2019 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package robustio wraps I/O functions that are prone to failure on Windows,
     6  // transparently retrying errors up to an arbitrary timeout.
     7  //
     8  // Errors are classified heuristically and retries are bounded, so the functions
     9  // in this package do not completely eliminate spurious errors. However, they do
    10  // significantly reduce the rate of failure in practice.
    11  //
    12  // If so, the error will likely wrap one of:
    13  // The functions in this package do not completely eliminate spurious errors,
    14  // but substantially reduce their rate of occurrence in practice.
    15  package robustio
    16  
    17  import "time"
    18  
    19  // Rename is like os.Rename, but on Windows retries errors that may occur if the
    20  // file is concurrently read or overwritten.
    21  //
    22  // (See golang.org/issue/31247 and golang.org/issue/32188.)
    23  func Rename(oldpath, newpath string) error {
    24  	return rename(oldpath, newpath)
    25  }
    26  
    27  // ReadFile is like os.ReadFile, but on Windows retries errors that may
    28  // occur if the file is concurrently replaced.
    29  //
    30  // (See golang.org/issue/31247 and golang.org/issue/32188.)
    31  func ReadFile(filename string) ([]byte, error) {
    32  	return readFile(filename)
    33  }
    34  
    35  // RemoveAll is like os.RemoveAll, but on Windows retries errors that may occur
    36  // if an executable file in the directory has recently been executed.
    37  //
    38  // (See golang.org/issue/19491.)
    39  func RemoveAll(path string) error {
    40  	return removeAll(path)
    41  }
    42  
    43  // IsEphemeralError reports whether err is one of the errors that the functions
    44  // in this package attempt to mitigate.
    45  //
    46  // Errors considered ephemeral include:
    47  //   - syscall.ERROR_ACCESS_DENIED
    48  //   - syscall.ERROR_FILE_NOT_FOUND
    49  //   - internal/syscall/windows.ERROR_SHARING_VIOLATION
    50  //
    51  // This set may be expanded in the future; programs must not rely on the
    52  // non-ephemerality of any given error.
    53  func IsEphemeralError(err error) bool {
    54  	return isEphemeralError(err)
    55  }
    56  
    57  // A FileID uniquely identifies a file in the file system.
    58  //
    59  // If GetFileID(name1) returns the same ID as GetFileID(name2), the two file
    60  // names denote the same file.
    61  // A FileID is comparable, and thus suitable for use as a map key.
    62  type FileID struct {
    63  	device, inode uint64
    64  }
    65  
    66  // GetFileID returns the file system's identifier for the file, and its
    67  // modification time.
    68  // Like os.Stat, it reads through symbolic links.
    69  func GetFileID(filename string) (FileID, time.Time, error) { return getFileID(filename) }