github.com/bananabytelabs/wazero@v0.0.0-20240105073314-54b22a776da8/internal/fsapi/file.go (about)

     1  package fsapi
     2  
     3  import experimentalsys "github.com/bananabytelabs/wazero/experimental/sys"
     4  
     5  // File includes methods not yet ready to document for end users, notably
     6  // non-blocking functionality.
     7  //
     8  // Particularly, Poll is subject to debate. For example, whether a user should
     9  // be able to choose how to implement timeout or not. Currently, this interface
    10  // allows the user to choose to sleep or use native polling, and which choice
    11  // they make impacts thread behavior as summarized here:
    12  // https://github.com/bananabytelabs/wazero/pull/1606#issuecomment-1665475516
    13  type File interface {
    14  	experimentalsys.File
    15  
    16  	// IsNonblock returns true if the file was opened with O_NONBLOCK, or
    17  	// SetNonblock was successfully enabled on this file.
    18  	//
    19  	// # Notes
    20  	//
    21  	//   - This might not match the underlying state of the file descriptor if
    22  	//     the file was not opened via OpenFile.
    23  	IsNonblock() bool
    24  
    25  	// SetNonblock toggles the non-blocking mode (O_NONBLOCK) of this file.
    26  	//
    27  	// # Errors
    28  	//
    29  	// A zero Errno is success. The below are expected otherwise:
    30  	//   - ENOSYS: the implementation does not support this function.
    31  	//   - EBADF: the file or directory was closed.
    32  	//
    33  	// # Notes
    34  	//
    35  	//   - This is like syscall.SetNonblock and `fcntl` with O_NONBLOCK in
    36  	//     POSIX. See https://pubs.opengroup.org/onlinepubs/9699919799/functions/fcntl.html
    37  	SetNonblock(enable bool) experimentalsys.Errno
    38  
    39  	// Poll returns if the file has data ready to be read or written.
    40  	//
    41  	// # Parameters
    42  	//
    43  	// The `flag` parameter determines which event to await, such as POLLIN,
    44  	// POLLOUT, or a combination like `POLLIN|POLLOUT`.
    45  	//
    46  	// The `timeoutMillis` parameter is how long to block for an event, or
    47  	// interrupted, in milliseconds. There are two special values:
    48  	//   - zero returns immediately
    49  	//   - any negative value blocks any amount of time
    50  	//
    51  	// # Results
    52  	//
    53  	// `ready` means there was data ready to read or written. False can mean no
    54  	// event was ready or `errno` is not zero.
    55  	//
    56  	// A zero `errno` is success. The below are expected otherwise:
    57  	//   - ENOSYS: the implementation does not support this function.
    58  	//   - ENOTSUP: the implementation does not the flag combination.
    59  	//   - EINTR: the call was interrupted prior to an event.
    60  	//
    61  	// # Notes
    62  	//
    63  	//   - This is like `poll` in POSIX, for a single file.
    64  	//     See https://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html
    65  	//   - No-op files, such as those which read from /dev/null, should return
    66  	//     immediately true, as data will never become available.
    67  	//   - See /RATIONALE.md for detailed notes including impact of blocking.
    68  	Poll(flag Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)
    69  }