Skip to content

Clarify TCPSocket::recv() and UDPSocket::recvfrom() documentation. #5623

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 15, 2018
Merged

Clarify TCPSocket::recv() and UDPSocket::recvfrom() documentation. #5623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion features/netsocket/TCPSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,9 @@ class TCPSocket : public Socket {
* @param data Destination buffer for data received from the host
* @param size Size of the buffer in bytes
* @return Number of received bytes on success, negative error
* code on failure
* code on failure. If no data is available to be received
* and the peer has performed an orderly shutdown,
* recv() returns 0.
*/
nsapi_size_or_error_t recv(void *data, nsapi_size_t size);

Expand Down
15 changes: 8 additions & 7 deletions features/netsocket/UDPSocket.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,17 +94,18 @@ class UDPSocket : public Socket {
nsapi_size_or_error_t sendto(const SocketAddress &address,
const void *data, nsapi_size_t size);

/** Receive a packet over a UDP socket
/** Receive a datagram over a UDP socket
*
* Receives data and stores the source address in address if address
* is not NULL. Returns the number of bytes received into the buffer.
* Receives a datagram and stores the source address in address if address
* is not NULL. Returns the number of bytes written into the buffer. If the
* datagram is larger than the buffer, the excess data is silently discarded.
*
* By default, recvfrom blocks until data is sent. If socket is set to
* non-blocking or times out, NSAPI_ERROR_WOULD_BLOCK is returned
* immediately.
* By default, recvfrom blocks until a datagram is received. If socket is set to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Query: Who or what receives the datagram? Please clarify for active voice.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "blocks until a datagram arrives"?

(POSIX version is much more wordy and specific, with a couple of "if no messages are available..." Don't know if it's worth spelling that out. Could compromise with "has arrived", to imply it may have already arrived before the call.)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like "blocks until a datagram arrives".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see much difference between "blocks until a datagram is received" and "blocks until a datagram arrives".

It might even confuse more. Datagram can arrive earlier that user calls this function. Then user receives the datagram from the network stack's buffer. So "datagram arrives" is not totally accurate. Should we clarify this a bit? I found it already clear for me, so I assume SW engineer understand accurately it already.

For a comparison, POSIX standard definition of this same function http://pubs.opengroup.org/onlinepubs/009695399/functions/recvfrom.html

And as this function is recvfrom() then the answer to "who receives" is just who ever calls this function.

* non-blocking or times out with no datagram, NSAPI_ERROR_WOULD_BLOCK
* is returned.
*
* @param address Destination for the source address or NULL
* @param data Destination buffer for data received from the host
* @param data Destination buffer for datagram received from the host
* @param size Size of the buffer in bytes
* @return Number of received bytes on success, negative error
* code on failure
Expand Down