1package fsapi
 2
 3import experimentalsys "github.com/tetratelabs/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/tetratelabs/wazero/pull/1606#issuecomment-1665475516
13type 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}