romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-08-04 15:46:12 +03:00
Code Issues Projects Releases Packages Wiki Activity

docs: limit close socket callback documentation to defined behavior

Browse source 
Remove socket function and polling details from the close socket callback
man page and clarify only the documented lifecycle guarantees.
This commit is contained in:
jayvenn21 2026-02-07 18:43:00 -05:00
parent 386e35cda6
commit 3730a98664
2 changed files with 10 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.md
View file

@ -100,11 +100,10 @@ writable.
The specified socket or file descriptor is no longer used by libcurl for any
active transfer. It might soon be added again. After libcurl signals
CURL_POLL_REMOVE, the application must stop monitoring that socket for
read and write events on libcurl's behalf. The pointer previously assigned
to the socket with curl_multi_assign(3) is forgotten by libcurl.
Applications must not rely on *socketp* to track idle connections. For
more on idle connection behavior, see CURLOPT_CLOSESOCKETFUNCTION(3).
CURL_POLL_REMOVE, the application must stop monitoring that socket on
libcurl's behalf. libcurl does not track idle connections. The pointer
previously assigned to the socket with curl_multi_assign(3) is forgotten by
libcurl. Applications must not rely on *socketp* to track idle connections.
When a socket is given a CURL_POLL_REMOVE value, it might be because libcurl
is going to close it, but it might also mean that it does not need any more

34
docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.md
View file

@ -50,36 +50,14 @@ than the transfer itself in the multi/share handle's connection cache.
# NOTES ON IDLE CONNECTIONS
When using the multi interface with a connection cache, applications must
not assume that sockets associated with idle connections behave the same
as active connections.
## Callback life cycle
The close socket callback is invoked when libcurl closes a socket it owns.
The callback and CURLOPT_CLOSESOCKETDATA(3) are copied from the *first* easy
handle that creates the connection. Changing this option on a subsequent
handle that creates the connection; changing this option on a subsequent
easy handle that reuses the same connection has no effect for that
connection. The callback is not invoked when an idle connection is
closed after CURL_CSELECT_ERR. Applications should not rely on the close
callback to be called for every socket that leaves use.
## Readiness events after CURL_POLL_REMOVE
Applications must not assume that receiving readiness events for a socket
implies that libcurl still expects the socket to be reported back via
curl_multi_socket_action(3). Readiness events may occur for reasons
outside libcurl's control, but libcurl provides no API for reporting such
events once a socket has been removed from polling. Applications
integrating with external polling systems must defensively handle
unexpected readiness events.
## Socket callback and idle sockets
After libcurl signals CURL_POLL_REMOVE for a socket, the application must
stop monitoring that socket on libcurl's behalf.
libcurl may still retain the connection internally for reuse. When the
socket has been removed, the pointer previously assigned to it with
curl_multi_assign(3) is forgotten by libcurl. libcurl does not track idle connections.
connection. The callback is not guaranteed to be called for every socket
that leaves use, for example when connections are kept alive in the
connection cache and reused. Applications must not assume the callback is
called for every socket lifecycle.
# DEFAULT