fd_sync_windows.go

     1  // Copyright 2026 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 poll
     6  
     7  import (
     8  	"internal/synctest"
     9  	"internal/syscall/windows"
    10  	"runtime"
    11  	"sync"
    12  	"sync/atomic"
    13  	"syscall"
    14  )
    15  
    16  // ioCancelState coordinates cancellation with synchronous I/O workers.
    17  // Its zero value is ready for use. The FD's directional locks permit at most
    18  // one read worker and one write worker at a time.
    19  type ioCancelState struct {
    20  	canceling  atomic.Bool
    21  	cancelDone sync.WaitGroup
    22  	// A worker clears its slot once its I/O returns, before sending the result.
    23  	workers [2]atomic.Pointer[syncIOWorkerState]
    24  }
    25  
    26  // begin publishes the worker before its closing check and returns its slot.
    27  // The worker must call end after I/O returns and before sending the result.
    28  func (s *ioCancelState) begin(worker *syncIOWorkerState) int {
    29  	for i := range s.workers {
    30  		if s.workers[i].CompareAndSwap(nil, worker) {
    31  			return i
    32  		}
    33  	}
    34  	// A caller bypassed a directional lock, or a worker did not clear its slot.
    35  	panic("too many synchronous I/O workers")
    36  }
    37  
    38  func (s *ioCancelState) end(slot int) {
    39  	// Clear the slot before waiting, so cancellation retries can finish.
    40  	s.workers[slot].Store(nil)
    41  	if s.canceling.Load() {
    42  		s.cancelDone.Wait()
    43  	}
    44  }
    45  
    46  // cancelIO requests cancellation of outstanding I/O. Close waits for completion
    47  // by waiting for the I/O callers to release their FD references.
    48  // The caller must have marked the FD closed and hold a reference to it.
    49  // Only one goroutine may call cancelIO.
    50  func (fd *FD) cancelIO() {
    51  	s := &fd.ioCancel
    52  	// Workers clear their slots before waiting in end, so retries can finish
    53  	// without waiting for result delivery. Add before publishing canceling, so
    54  	// a worker seen by the scan cannot return from end before cancellation ends.
    55  	s.cancelDone.Add(1)
    56  	s.canceling.Store(true)
    57  	defer s.cancelDone.Done()
    58  
    59  	// Workers published after a scan see closing and skip I/O. We only
    60  	// need to remember successful cancellation for each slot.
    61  	var canceled [2]bool
    62  	first := true
    63  	for {
    64  		var retry bool
    65  		for i := range s.workers {
    66  			worker := s.workers[i].Load()
    67  			if worker == nil || canceled[i] {
    68  				continue
    69  			}
    70  			switch err := windows.CancelSynchronousIo(worker.thread); err {
    71  			case nil:
    72  				// The thread has only this I/O request to cancel. end keeps
    73  				// it alive and unavailable for reuse until cancelIO returns.
    74  				canceled[i] = true
    75  			case syscall.ERROR_NOT_FOUND:
    76  				// I/O may have returned, or may not have been submitted yet.
    77  				retry = true
    78  			default:
    79  				panic(err)
    80  			}
    81  		}
    82  		if first {
    83  			first = false
    84  			// Also cancel overlapped and externally issued I/O, including I/O
    85  			// blocking lazy initialization, even if no worker is published.
    86  			// Target workers first so their cancellation is known separately.
    87  			switch err := syscall.CancelIoEx(fd.Sysfd, nil); err {
    88  			case nil, syscall.ERROR_NOT_FOUND:
    89  			case windows.ERROR_INVALID_HANDLE:
    90  				// The handle may have been closed outside this FD.
    91  				// Let destroy report the error from CloseHandle.
    92  			default:
    93  				panic(err)
    94  			}
    95  		}
    96  		if !retry {
    97  			return
    98  		}
    99  		// ERROR_NOT_FOUND may mean a worker passed its closing check but
   100  		// has not submitted I/O yet. It can still submit a blocking request,
   101  		// so we must retry. Alternatively, I/O has completed but the worker
   102  		// has not cleared its slot yet. Yield to let the worker make progress.
   103  		runtime.Gosched()
   104  	}
   105  }
   106  
   107  // runtime_startThread starts a goroutine locked to a fresh OS thread. The
   108  // thread exits when the function returns; it must not call UnlockOSThread.
   109  func runtime_startThread(func())
   110  
   111  // runtime_threadHandle returns the runtime-owned handle of the current worker
   112  // thread. It may only be called from a runtime_startThread worker. The handle
   113  // is valid until the worker returns and must not be closed by the caller.
   114  func runtime_threadHandle() syscall.Handle
   115  
   116  type syncIORequest struct {
   117  	fd     *FD
   118  	submit func(syscall.Handle, []byte, *uint32, *syscall.Overlapped) error
   119  	buf    []byte
   120  }
   121  
   122  type syncIOResult struct {
   123  	qty uint32
   124  	err error
   125  }
   126  
   127  type syncIOWorker struct {
   128  	state *syncIOWorkerState
   129  }
   130  
   131  // The running worker references only its state, not the cached owner. This
   132  // lets the owner's cleanup stop the thread when sync.Pool discards it.
   133  type syncIOWorkerState struct {
   134  	requests chan syncIORequest
   135  	results  chan syncIOResult
   136  	thread   syscall.Handle // borrowed from runtime; set before begin
   137  }
   138  
   139  // Reuse idle workers through sync.Pool's per-P caches. Active workers are not
   140  // limited: they may all be blocked in Read while another must run Write.
   141  // Discarded owners shut down their idle workers through a cleanup.
   142  var idleSyncIOWorkers sync.Pool
   143  
   144  func acquireSyncIOWorker() *syncIOWorker {
   145  	// A worker created in a synctest bubble must exit within that bubble;
   146  	// neither its goroutine nor its channels may enter the shared cache.
   147  	inBubble := synctest.IsInBubble()
   148  	if !inBubble {
   149  		if worker := idleSyncIOWorkers.Get(); worker != nil {
   150  			return worker.(*syncIOWorker)
   151  		}
   152  	}
   153  	state := &syncIOWorkerState{
   154  		requests: make(chan syncIORequest),
   155  		results:  make(chan syncIOResult),
   156  	}
   157  	runtime_startThread(state.run)
   158  	worker := &syncIOWorker{state: state}
   159  	if !inBubble {
   160  		runtime.AddCleanup(worker, (*syncIOWorkerState).stop, state)
   161  	}
   162  	return worker
   163  }
   164  
   165  func (worker *syncIOWorker) release() {
   166  	if synctest.IsInBubble() {
   167  		worker.state.stop()
   168  	} else {
   169  		idleSyncIOWorkers.Put(worker)
   170  	}
   171  	runtime.KeepAlive(worker)
   172  }
   173  
   174  func (worker *syncIOWorkerState) stop() {
   175  	close(worker.requests)
   176  }
   177  
   178  func (worker *syncIOWorkerState) run() {
   179  	worker.thread = runtime_threadHandle()
   180  
   181  	// Reuse the result because passing its address to submit makes it escape.
   182  	var result syncIOResult
   183  	for request := range worker.requests {
   184  		slot := request.fd.ioCancel.begin(worker)
   185  		if request.fd.closing() {
   186  			result.err = errClosing(request.fd.isFile)
   187  		} else {
   188  			result.err = request.submit(request.fd.Sysfd, request.buf, &result.qty, nil)
   189  		}
   190  		// Wait for cancellation before the result lets the caller reuse or
   191  		// stop this worker.
   192  		request.fd.ioCancel.end(slot)
   193  		// Do not retain the caller's file or buffer while this worker is idle.
   194  		request = syncIORequest{}
   195  		worker.results <- result
   196  		result = syncIOResult{}
   197  	}
   198  }
   199  
   200  // execSyncIO queues synchronous pipe I/O to a dedicated worker. The caller
   201  // retains the I/O lock, FD reference, and buffer until the worker returns,
   202  // but does not need to reserve its own OS thread.
   203  func (fd *FD) execSyncIO(submit func(syscall.Handle, []byte, *uint32, *syscall.Overlapped) error, buf []byte) (uint32, error) {
   204  	worker := acquireSyncIOWorker()
   205  	worker.state.requests <- syncIORequest{fd, submit, buf}
   206  	result := <-worker.state.results
   207  	worker.release()
   208  	return result.qty, result.err
   209  }
   210
View as plain text