comments, formatting

Signed-off-by: Edoardo Vacchi <[email protected]>

internal/sysfs/poll_darwin.go

@@ -6,34 +6,41 @@ import (
 	"github.com/tetratelabs/wazero/experimental/sys"
 )
 
+// PollFd is the struct to query for file descriptor events using poll.
 type PollFd struct {
-	fd      int32 /* file descriptor */
-	events  int16 /* requested events */
-	revents int16 /* returned events */
+	// fd is the file descriptor.
+	fd int32
+	// events is a bitmap containing the requested events.
+	events int16
+	// revents is a bitmap containing the returned events.
+	revents int16
 }
 
+// NewPollFd is a constructor for PollFd that abstracts the platform-specific type of file descriptors.
 func NewPollFd(fd uintptr, events, revents int16) PollFd {
 	return PollFd{fd: int32(fd), events: events, revents: revents}
 }
 
 const (
-	_POLLIN = 0x0001 /* any readable data available */
+	// _POLLIN subscribes a notification when any readable data is available.
+	_POLLIN = 0x0001
 )
 
+// poll exposes the corresponding libc function on Darwin.
 func poll(fds []PollFd, timeout int) (n int, err sys.Errno) {
-	nilptr := unsafe.Pointer(nil)
-	fdptr := nilptr
-	if len(fds) > 0 {
-		fdptr = unsafe.Pointer(&fds[0])
+	var fdptr *PollFd
+	nfds := len(fds)
+	if nfds > 0 {
+		fdptr = &fds[0]
 	}
 	n1, _, errno := syscall_syscall6(
 		libc_poll_trampoline_addr,
-		uintptr(fdptr),
-		uintptr(len(fds)),
+		uintptr(unsafe.Pointer(fdptr)),
+		uintptr(nfds),
 		uintptr(timeout),
-		uintptr(nilptr),
-		uintptr(nilptr),
-		uintptr(nilptr))
+		uintptr(unsafe.Pointer(nil)),
+		uintptr(unsafe.Pointer(nil)),
+		uintptr(unsafe.Pointer(nil)))
 	return int(n1), sys.UnwrapOSError(errno)
 }
 

internal/sysfs/poll_linux.go

@@ -7,54 +7,50 @@ import (
 	"github.com/tetratelabs/wazero/experimental/sys"
 )
 
+// PollFd is the struct to query for file descriptor events using poll.
 type PollFd struct {
-	fd      int32 /* file descriptor */
-	events  int16 /* requested events */
-	revents int16 /* returned events */
+	// fd is the file descriptor.
+	fd int32
+	// events is a bitmap containing the requested events.
+	events int16
+	// revents is a bitmap containing the returned events.
+	revents int16
 }
 
+// NewPollFd is a constructor for PollFd that abstracts the platform-specific type of file descriptors.
 func NewPollFd(fd uintptr, events, revents int16) PollFd {
 	return PollFd{fd: int32(fd), events: events, revents: revents}
 }
 
-/* These are specified by iBCS2 */
 const (
+	// _POLLIN subscribes a notification when any readable data is available.
 	_POLLIN = 0x0001
 )
 
-const (
-	_NSIG       = 64
-	_NSIG_BPW   = 32
-	_NSIG_WORDS = (_NSIG / _NSIG_BPW)
-)
-
-type sigset_t struct {
-	sig [_NSIG_WORDS]uint64
-}
-
-func ppoll(fds []PollFd, timeout *syscall.Timespec, sigmask *sigset_t) (n int, err sys.Errno) {
-	if len(fds) == 0 {
-		return _ppoll(nil, 0, timeout, sigmask)
-	}
-	return _ppoll(&fds[0], len(fds), timeout, sigmask)
-}
-
+// poll is defined in terms of ppoll on Linux.
 func poll(fds []PollFd, timeout int) (n int, err sys.Errno) {
-	var ts *syscall.Timespec
+	var ts syscall.Timespec
 	if timeout >= 0 {
-		ts = new(syscall.Timespec)
-		*ts = syscall.NsecToTimespec(int64(timeout) * 1e6)
+		ts = syscall.NsecToTimespec(int64(timeout) * 1e6)
 	}
-	return ppoll(fds, ts, nil)
+	return ppoll(fds, &ts)
 }
 
-func _ppoll(fd *PollFd, nfd int, timespec *syscall.Timespec, sigmask *sigset_t) (n int, err sys.Errno) {
+// ppoll is a poll variant that allows to subscribe to a mask of signals.
+// However, we do not need such mask, so the corresponding argument is always nil.
+func ppoll(fds []PollFd, timespec *syscall.Timespec) (n int, err sys.Errno) {
+	var fdptr *PollFd
+	nfd := len(fds)
+	if nfd != 0 {
+		fdptr = &fds[0]
+	}
+
 	n1, _, errno := syscall.Syscall6(
 		uintptr(syscall.SYS_PPOLL),
-		uintptr(unsafe.Pointer(fd)),
+		uintptr(unsafe.Pointer(fdptr)),
 		uintptr(nfd),
 		uintptr(unsafe.Pointer(timespec)),
-		uintptr(unsafe.Pointer(sigmask)),
+		uintptr(unsafe.Pointer(nil)), // sigmask is currently always ignored
 		uintptr(unsafe.Pointer(nil)),
 		uintptr(unsafe.Pointer(nil)))
 

internal/sysfs/poll_windows.go

@@ -15,15 +15,22 @@ var (
 )
 
 const (
+	// _POLLRDNORM subscribes to normal data for read.
 	_POLLRDNORM = 0x0100
+	// _POLLRDBAND subscribes to priority band (out-of-band) data for read.
 	_POLLRDBAND = 0x0200
-	_POLLIN     = (_POLLRDNORM | _POLLRDBAND)
+	// _POLLIN subscribes a notification when any readable data is available.
+	_POLLIN = (_POLLRDNORM | _POLLRDBAND)
 )
 
+// PollFd is the struct to query for file descriptor events using poll.
 type PollFd struct {
-	fd      uintptr /* file descriptor */
-	events  int16   /* requested events */
-	revents int16   /* returned events */
+	// fd is the file descriptor.
+	fd uintptr
+	// events is a bitmap containing the requested events.
+	events int16
+	// revents is a bitmap containing the returned events.
+	revents int16
 }
 
 // NewPollFd is a constructor for PollFd that abstracts the platform-specific type of file descriptors.
@@ -62,7 +69,7 @@ func pollWithContext(ctx context.Context, fds []PollFd, timeout int) (int, sys.E
 		return -1, sys.ENOSYS
 	}
 
-	regular, pipes, sockets, errno := ftypes(fds)
+	regular, pipes, sockets, errno := partionByFtype(fds)
 	nregular := len(regular)
 	if errno != 0 {
 		return -1, errno
@@ -117,7 +124,9 @@ func peekAll(pipes, sockets []PollFd) (npipes, nsockets int, errno sys.Errno) {
 		return
 	}
 
-	nsockets, errno = peekSockets(sockets)
+	// Invoke wsaPoll with a 0-timeout to avoid blocking.
+	// Timeouts are handled in pollWithContext instead.
+	nsockets, errno = wsaPoll(sockets, 0)
 	if errno != 0 {
 		return
 	}
@@ -143,14 +152,17 @@ func peekPipes(fds []PollFd) (n int, errno sys.Errno) {
 	return
 }
 
-func peekSockets(fds []PollFd) (n int, errno sys.Errno) {
+// wsaPoll is the WSAPoll function from winsock2.
+//
+// See https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsapoll
+func wsaPoll(fds []PollFd, timeout int) (n int, errno sys.Errno) {
 	if len(fds) > 0 {
 		sockptr := &fds[0]
 		ns, _, e := syscall.SyscallN(
 			procWSAPoll.Addr(),
 			uintptr(unsafe.Pointer(sockptr)),
 			uintptr(len(fds)),
-			uintptr(0))
+			uintptr(timeout))
 		if e != 0 {
 			return -1, sys.UnwrapOSError(e)
 		}
@@ -159,6 +171,7 @@ func peekSockets(fds []PollFd) (n int, errno sys.Errno) {
 	return
 }
 
+// ftype is a type of file that can be handled by poll.
 type ftype uint8
 
 const (
@@ -167,7 +180,9 @@ const (
 	ftype_socket
 )
 
-func ftypes(fds []PollFd) (regular, pipe, socket []PollFd, errno sys.Errno) {
+// partionByFtype checks the type of each fd in fds and returns 3 distinct partitions
+// for regular files, named pipes and sockets.
+func partionByFtype(fds []PollFd) (regular, pipe, socket []PollFd, errno sys.Errno) {
 	for _, pfd := range fds {
 		t, errno := ftypeOf(pfd.fd)
 		if errno != 0 {
@@ -185,6 +200,7 @@ func ftypes(fds []PollFd) (regular, pipe, socket []PollFd, errno sys.Errno) {
 	return
 }
 
+// ftypeOf checks the type of fd and return the corresponding ftype.
 func ftypeOf(fd uintptr) (ftype, sys.Errno) {
 	h := syscall.Handle(fd)
 	t, err := syscall.GetFileType(h)