Socket.EndSend reference doc inaccuracy

[ghogen]

This issue was reported by a .NET user a while ago via a different channel:

Hi alll, no authoritative response has been given on this in several discussions in the past, so I decided to report this as a documentation bug, because there is an obvious conflict in the documentation of the Socket.BeginSend and Socket.EndSend methods even in the latest .NET framework version. MSDN says in Socket.BeginSend: "When your application calls BeginSend, the system will use a separate thread to execute the specified callback method, and will block on EndSend until the Socket sends the number of bytes requested or throws an exception." From this sentence I infer, that BeginSend queues ALL data for sending or there will be an exception. But let's have a look what MSDN says in Socket.EndSend: "If you are using a connection-oriented protocol, EndSend will block until some of the buffer was sent. If the return value from EndSend indicates that the buffer was not completely sent, call the BeginSend method again, modifying the buffer to hold the unsent data." This sentence says, that EndSend might succeed even with less bytes sent than requested for connection-oriented protocols. Since it is realy important to know what the real behaviour of these methods is, the documentation should be fixed (or clariefied) to make this very old problem finally clear. According to our tests EndSend never returns less bytes than requested when it succeeds even for very large (MB) sents. So can you please explain to the public the behaviour of these two methods? Does it play a role if the socket is set to nonblocking? Thank you very much. Alex

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 81f71ba2-4ddb-acf3-f556-36c4b0a1c0a4
• Version Independent ID: 50fe175a-aac1-78e9-4a95-28e68c3c54d5
• Content: Socket.BeginSend Method (System.Net.Sockets)
• Content Source: xml/System.Net.Sockets/Socket.xml
• Product: dotnet-api
• GitHub Login: @karelz
• Microsoft Alias: ncldev

[mairaw]

Thanks @ghogen. @davidsh can you take a look at this? It's feedback regarding https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.beginsend and https://docs.microsoft.com/en-us/dotnet/api/system.net.sockets.socket.endsend. Thanks!

[davidsh]

cc: @stephentoub @rmkerr @karelz

[mairaw]

@stephentoub @rmkerr @karelz can one of you comment on this? Thanks!

[rmkerr]

There definitely is some conflicting info here. From the BeginSend docs:

When your application calls BeginSend, the system will use a separate thread to execute the specified callback method, and will block on EndSend until the Socket sends the number of bytes requested or throws an exception.

And from the EndSend docs:

If you are using a connection-oriented protocol, EndSend will block until some of the buffer was sent. If the return value from EndSend indicates that the buffer was not completely sent, call the BeginSend method again, modifying the buffer to hold the unsent data.

Unless someone else already knows the answer, I'll take a look at the code and see if I can find out what info is correct.

[rmkerr]

The EndSend docs are the correct ones. BeginSend is implemented using the WSASend function, which provides the following explanation (source):

If the socket is non-blocking and stream-oriented, and there is not sufficient space in the transport's buffer, WSASend will return with only part of the application's buffers having been consumed.

I'm not sure of the exact buffer sizes required to trigger this behavior, but it does appear to be possible. We should update the BeginSend docs to reflect the actual behavior, since there does seem to be some confusion around this issue.