@@ -204,23 +204,37 @@ added: v0.11.4
204
204
-->
205
205
206
206
* ` options ` {Object} Options containing connection details. Check
207
- [ ` net.createConnection() ` ] [ ] for the format of the options
208
- * ` callback ` {Function} Callback function that receives the created socket
209
- * Returns: {stream.Duplex}
207
+ [ ` net.createConnection() ` ] [ ] for the format of the options. For custom agents,
208
+ this object is passed to the custom ` createConnection ` function.
209
+ * ` callback ` {Function} (Optional, primarily for custom agents) A function to be
210
+ called by a custom ` createConnection ` implementation when the socket is
211
+ created, especially for asynchronous operations.
212
+ * ` err ` {Error | null} An error object if socket creation failed.
213
+ * ` socket ` {stream.Duplex} The created socket.
214
+ * Returns: {stream.Duplex} The created socket. This is returned by the default
215
+ implementation or by a custom synchronous ` createConnection ` implementation.
216
+ If a custom ` createConnection ` uses the ` callback ` for asynchronous
217
+ operation, this return value might not be the primary way to obtain the socket.
210
218
211
219
Produces a socket/stream to be used for HTTP requests.
212
220
213
- By default, this function is the same as [ ` net.createConnection() ` ] [ ] . However,
214
- custom agents may override this method in case greater flexibility is desired.
221
+ By default, this function behaves identically to [ ` net.createConnection(options) ` ] [ ] ,
222
+ synchronously returning the created socket. The optional ` callback ` parameter in the
223
+ signature is ** not** used by this default implementation.
215
224
216
- A socket/stream can be supplied in one of two ways: by returning the
217
- socket/stream from this function, or by passing the socket/stream to ` callback ` .
225
+ However, custom agents may override this method to provide greater flexibility,
226
+ for example, to create sockets asynchronously. When overriding ` createConnection ` :
218
227
219
- This method is guaranteed to return an instance of the {net.Socket} class,
220
- a subclass of {stream.Duplex}, unless the user specifies a socket
221
- type other than {net.Socket}.
228
+ 1 . ** Synchronous socket creation** : The overriding method can return the
229
+ socket/stream directly.
230
+ 2 . ** Asynchronous socket creation** : The overriding method can accept the ` callback `
231
+ and pass the created socket/stream to it (e.g., ` callback(null, newSocket) ` ).
232
+ If an error occurs during socket creation, it should be passed as the first
233
+ argument to the ` callback ` (e.g., ` callback(err) ` ).
222
234
223
- ` callback ` has a signature of ` (err, stream) ` .
235
+ The agent will call the provided ` createConnection ` function with ` options ` and
236
+ this internal ` callback ` . The ` callback ` provided by the agent has a signature
237
+ of ` (err, stream) ` .
224
238
225
239
### ` agent.keepSocketAlive(socket) `
226
240
0 commit comments