net: deprecate _setSimultaneousAccepts() undocumented function

This is an undocumented utility function that is of questionable
utility.

Fixes: #18391

PR-URL: #23760
Reviewed-By: Ben Noordhuis <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>

Author: jasnell

doc/api/deprecations.md

@@ -2264,6 +2264,20 @@ undocumented `COUNTER_NET_SERVER_CONNECTION()`,
 `COUNTER_HTTP_SERVER_RESPONSE()`, `COUNTER_HTTP_CLIENT_REQUEST()`, and
 `COUNTER_HTTP_CLIENT_RESPONSE()` functions have been deprecated.
 
+<a id="DEP00XX"></a>
+### DEP00XX: net._setSimultaneousAccepts()
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/23760
+    description: Runtime deprecation.
+-->
+
+The undocumented `net._setSimultaneousAccepts()` function was originally
+intended for debugging and performance tuning when using the `child_process`
+and `cluster` modules on Windows. The function is not generally useful and
+is being removed. See discussion here:
+https://github.com/nodejs/node/issues/18391
 
 [`--pending-deprecation`]: cli.html#cli_pending_deprecation
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size

lib/internal/child_process.js

@@ -604,8 +604,7 @@ function setupChannel(target, channel) {
 
     // Update simultaneous accepts on Windows
     if (process.platform === 'win32') {
-      handle._simultaneousAccepts = false;
-      net._setSimultaneousAccepts(handle);
+      handle.setSimultaneousAccepts(false);
     }
 
     // Convert handle object
@@ -700,8 +699,8 @@ function setupChannel(target, channel) {
         message = message.msg;
 
       // Update simultaneous accepts on Windows
-      if (obj.simultaneousAccepts) {
-        net._setSimultaneousAccepts(handle);
+      if (obj.simultaneousAccepts && process.platform === 'win32') {
+        handle.setSimultaneousAccepts(true);
       }
     } else if (this._handleQueue &&
                !(message && (message.cmd === 'NODE_HANDLE_ACK' ||

lib/net.js

@@ -1668,11 +1668,18 @@ Server.prototype.unref = function() {
 };
 
 var _setSimultaneousAccepts;
+var warnSimultaneousAccepts = true;
 
 if (process.platform === 'win32') {
   var simultaneousAccepts;
 
   _setSimultaneousAccepts = function(handle) {
+    if (warnSimultaneousAccepts) {
+      process.emitWarning(
+        'net._setSimultaneousAccepts() is deprecated and will be removed.',
+        'DeprecationWarning', 'DEP00XX');
+      warnSimultaneousAccepts = false;
+    }
     if (handle === undefined) {
       return;
     }
@@ -1688,7 +1695,14 @@ if (process.platform === 'win32') {
     }
   };
 } else {
-  _setSimultaneousAccepts = function() {};
+  _setSimultaneousAccepts = function() {
+    if (warnSimultaneousAccepts) {
+      process.emitWarning(
+        'net._setSimultaneousAccepts() is deprecated and will be removed.',
+        'DeprecationWarning', 'DEP00XX');
+      warnSimultaneousAccepts = false;
+    }
+  };
 }
 
 module.exports = {

test/parallel/test-net-deprecated-setsimultaneousaccepts.js

@@ -0,0 +1,16 @@
+// Flags: --no-warnings
+'use strict';
+
+const {
+  expectWarning
+} = require('../common');
+const {
+  _setSimultaneousAccepts
+} = require('net');
+
+expectWarning(
+  'DeprecationWarning',
+  'net._setSimultaneousAccepts() is deprecated and will be removed.',
+  'DEP00XX');
+
+_setSimultaneousAccepts();