[PATCH] recvmmsg.2: correct since fields and correct specification of the timeout parameter

[PATCH] recvmmsg.2: correct since fields and correct specification of the timeout parameter

[Elie De Brauwer]

Hello all,

After playing with and coming up with the example I bumped into some issues
with the current page.

The trivial ones:
 * The page states it was added in 2.6.32 but it is only added in 2.6.33
   (ref: http://kernelnewbies.org/Linux_2_6_33)
 * The MSG_WAITFORONE flag was in turn only added in 2.6.34 
   (ref: http://kernelnewbies.org/Linux_2_6_34)

The less trivial one, if you read the current manpage it seems like the 
timeout option is like a 'free' select/poll call. When reading the page
my impression is you call recvmmsg with a timeout set, that it will not
be able to block indefinitely. However this is not the case. You can
already see this in my example in my previous patch, bash transmits a UDP
packet every 250 msecs, but my demo app seems to recieve 5 packets while
the timeout is only 1 second.

If you look in the code ( http://lxr.linux.no/linux+v3.2/net/socket.c#L2201 )
of __sys_recvmmsg() you can clearly see that in pseudocode it does something
like:
poll_select_set_timeout();
while(datagrams < vlen) {
   err = __sys_recvmsg();
   if (err < 0 ) break
   datagrams++;
   if (timeout) {
     // Update time 
     if (timeout->tv_sec < 0) {
        break;
     }
   }
}

Hence three conditions result in recvmmsg() to return:
 - error in recvmmsg()
 - vlen datagrams received
 - timeout expiration.

But the timeout is only checked *after* __sys_recvmsg(), which may be 
blocking has returned, hence when working in blocking mode and the flow of
incoming data stops all of a sudden, recvmmsg() will also block, even if 
a timeout is set. And this is not what I understood from the original 
page.

A second case, in nonblocking mode, you can also specify a timeout, 
if a large amount of data is available, and the timeout is extremely sharp
it might be that the timeout can also cause an exit from this function
even if data is available in the socket.

The patch belows tries to reword the existing paragraphs to make it reflect
the information stated above.

btw, this patch is isolated from the example patch because they deal with
two separate things actually.

my 2 cents
E. 

---
 man2/recvmmsg.2 |   22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
index 3252be7..abcee5b 100644
--- a/man2/recvmmsg.2
+++ b/man2/recvmmsg.2
@@ -93,7 +93,7 @@ The flags are the same as documented for
 .BR recvmsg (2),
 with the following addition:
 .TP
-.B MSG_WAITFORONE
+.BR MSG_WAITFORONE " (since Linux 2.6.34)"
 Turns on
 .B MSG_DONTWAIT
 after the first message has been received.
@@ -105,24 +105,26 @@ argument points to a
 (see
 .BR clock_gettime (2))
 defining a timeout (seconds plus nanoseconds) for the receive operation.
-(This interval will be rounded up to the system clock granularity,
-and kernel scheduling delays mean that the blocking interval
-may overrun by a small amount.)
 If
 .I timeout
 is
 .I NULL
-then the operation blocks indefinitely.
+then the timeout is not taken into account.
 
 A blocking
 .BR recvmmsg ()
 call blocks until
 .I vlen
-messages have been received
-or until the timeout expires.
+messages have been received,
+or the timeout expires, or until a reception error occurs. 
+The timeout expiration is checked each time a message has 
+been received in a buffer. Hence a blocking call may block
+indefinitely if no messages are arriving.
 A nonblocking call reads as many messages as are available
-(up to the limit specified by
-.IR vlen )
+(up to the limits specified by
+.IR vlen
+and
+.IR timeout)
 and returns immediately.
 
 On return from
@@ -158,7 +160,7 @@ is invalid.
 .SH VERSIONS
 The
 .BR recvmmsg ()
-system call was added in Linux 2.6.32.
+system call was added in Linux 2.6.33.
 Support in glibc was added in version 2.12.
 .SH CONFORMING TO
 .BR recvmmsg ()
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2: correct since fields and correct specification of the timeout parameter

[Michael Kerrisk (man-pages)]

Hello Elie

On Wed, Dec 19, 2012 at 11:37 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hello all,
>
> After playing with and coming up with the example I bumped into some issues
> with the current page.
>
> The trivial ones:
>  * The page states it was added in 2.6.32 but it is only added in 2.6.33
>    (ref: http://kernelnewbies.org/Linux_2_6_33)
>  * The MSG_WAITFORONE flag was in turn only added in 2.6.34
>    (ref: http://kernelnewbies.org/Linux_2_6_34)
>
> The less trivial one, if you read the current manpage it seems like the
> timeout option is like a 'free' select/poll call. When reading the page
> my impression is you call recvmmsg with a timeout set, that it will not
> be able to block indefinitely. However this is not the case. You can
> already see this in my example in my previous patch, bash transmits a UDP
> packet every 250 msecs, but my demo app seems to recieve 5 packets while
> the timeout is only 1 second.
>
> If you look in the code ( http://lxr.linux.no/linux+v3.2/net/socket.c#L2201 )
> of __sys_recvmmsg() you can clearly see that in pseudocode it does something
> like:
> poll_select_set_timeout();
> while(datagrams < vlen) {
>    err = __sys_recvmsg();
>    if (err < 0 ) break
>    datagrams++;
>    if (timeout) {
>      // Update time
>      if (timeout->tv_sec < 0) {
>         break;
>      }
>    }
> }
>
> Hence three conditions result in recvmmsg() to return:
>  - error in recvmmsg()
>  - vlen datagrams received
>  - timeout expiration.
>
> But the timeout is only checked *after* __sys_recvmsg(), which may be
> blocking has returned, hence when working in blocking mode and the flow of
> incoming data stops all of a sudden, recvmmsg() will also block, even if
> a timeout is set. And this is not what I understood from the original
> page.
>
> A second case, in nonblocking mode, you can also specify a timeout,
> if a large amount of data is available, and the timeout is extremely sharp
> it might be that the timeout can also cause an exit from this function
> even if data is available in the socket.
>
> The patch belows tries to reword the existing paragraphs to make it reflect
> the information stated above.
>
> btw, this patch is isolated from the example patch because they deal with
> two separate things actually.

It was god that you split the patch this way, but it would be even
better to split it further. The version stuff should be it's a
separate patch. The timeout stuff is complex, and it looks to me like
a kernel bug. Could you resubmit as two patches please.

Thanks

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] recvmmsg.2 Updated since fields for recvmmsg and MSG_WAITFORNONE

[Elie De Brauwer]

All,

This patch isolates the since/version related fixes as requested. 
This change introduces the following delta:
 * The page states it was added in 2.6.32 but it is only added in 2.6.33
   (ref: http://kernelnewbies.org/Linux_2_6_33)
 * The MSG_WAITFORONE flag was in turn only added in 2.6.34
   (ref: http://kernelnewbies.org/Linux_2_6_34)

my 2 cents
E.

---
 man2/recvmmsg.2 |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
index a7b00d4..85e4080 100644
--- a/man2/recvmmsg.2
+++ b/man2/recvmmsg.2
@@ -95,7 +95,7 @@ The flags are the same as documented for
 .BR recvmsg (2),
 with the following addition:
 .TP
-.B MSG_WAITFORONE
+.BR MSG_WAITFORONE " (since Linux 2.6.34)"
 Turns on
 .B MSG_DONTWAIT
 after the first message has been received.
@@ -160,7 +160,7 @@ is invalid.
 .SH VERSIONS
 The
 .BR recvmmsg ()
-system call was added in Linux 2.6.32.
+system call was added in Linux 2.6.33.
 Support in glibc was added in version 2.12.
 .SH CONFORMING TO
 .BR recvmmsg ()
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] recvmmsg.2 Updated timeout documentation

[Elie De Brauwer]

All,

This is the second part of my recvmmsg update, this is splitted off from the 
version related information.

At first I considered the possibility of it being a kernel patch too, but I
compared the original commit and checked if it might have been evolved
upstream but short from the WAITFORNONE addition it has not.

In any case, when operating in non-blocking mode, the timeout is taken into
account, which could mean that recvmmsg() returns while data is still 
available (which was not clearly stated). (Combination of much data to 
copy and a very sharp timeout).

And when operating in blocking mode, the timeout is only taken into account
after the reception of data. Which may mean infinity when no data arrives. 
Having the timeout function in kernel space would probably imply calling 
something (e)poll()/select()-ish before attempting to recieve.

my 2 cents
E.

---
 man2/recvmmsg.2 |   18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
index 85e4080..b16335f 100644
--- a/man2/recvmmsg.2
+++ b/man2/recvmmsg.2
@@ -107,24 +107,26 @@ argument points to a
 (see
 .BR clock_gettime (2))
 defining a timeout (seconds plus nanoseconds) for the receive operation.
-(This interval will be rounded up to the system clock granularity,
-and kernel scheduling delays mean that the blocking interval
-may overrun by a small amount.)
 If
 .I timeout
 is
 .I NULL
-then the operation blocks indefinitely.
+then the timeout is not taken into account.
 
 A blocking
 .BR recvmmsg ()
 call blocks until
 .I vlen
-messages have been received
-or until the timeout expires.
+messages have been received,
+or the timeout expires, or until a reception error occurs. 
+The timeout expiration is checked each time a message has 
+been received in a buffer. Hence a blocking call may block
+indefinitely if no messages are arriving.
 A nonblocking call reads as many messages as are available
-(up to the limit specified by
-.IR vlen )
+(up to the limits specified by
+.IR vlen
+and
+.IR timeout)
 and returns immediately.
 
 On return from
-- 
1.7.10.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2 Updated since fields for recvmmsg and MSG_WAITFORNONE

[Michael Kerrisk (man-pages)]

Hello Elie,

On Sun, Dec 23, 2012 at 12:47 PM, Elie De Brauwer
<eliedebrauwer-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> All,
>
> This patch isolates the since/version related fixes as requested.
> This change introduces the following delta:
>  * The page states it was added in 2.6.32 but it is only added in 2.6.33
>    (ref: http://kernelnewbies.org/Linux_2_6_33)
>  * The MSG_WAITFORONE flag was in turn only added in 2.6.34
>    (ref: http://kernelnewbies.org/Linux_2_6_34)

Thanks. Applied.

Cheers,

Michael


> ---
>  man2/recvmmsg.2 |    4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/man2/recvmmsg.2 b/man2/recvmmsg.2
> index a7b00d4..85e4080 100644
> --- a/man2/recvmmsg.2
> +++ b/man2/recvmmsg.2
> @@ -95,7 +95,7 @@ The flags are the same as documented for
>  .BR recvmsg (2),
>  with the following addition:
>  .TP
> -.B MSG_WAITFORONE
> +.BR MSG_WAITFORONE " (since Linux 2.6.34)"
>  Turns on
>  .B MSG_DONTWAIT
>  after the first message has been received.
> @@ -160,7 +160,7 @@ is invalid.
>  .SH VERSIONS
>  The
>  .BR recvmmsg ()
> -system call was added in Linux 2.6.32.
> +system call was added in Linux 2.6.33.
>  Support in glibc was added in version 2.12.
>  .SH CONFORMING TO
>  .BR recvmmsg ()
> --
> 1.7.10.4
>



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface"; http://man7.org/tlpi/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2 Updated timeout documentation

[Michael Kerrisk (man-pages)]

Elie,

> In any case, when operating in non-blocking mode, the timeout is taken into
> account, which could mean that recvmmsg() returns while data is still
> available (which was not clearly stated). (Combination of much data to
> copy and a very sharp timeout).

Can you say more about what you see/understand with nonblocking mode.
I don't understand what you mean here (and it doesn't fit with what I
am seeing on testing). Nonblocking mode should, I believe, always mean
an immediate return, regardless of any timeout.

Thanks,

Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] recvmmsg.2 Updated timeout documentation

[Elie De Brauwer]

On 12/23/2012 07:30 PM, Michael Kerrisk (man-pages) wrote:
> Elie,
>
>> In any case, when operating in non-blocking mode, the timeout is taken into
>> account, which could mean that recvmmsg() returns while data is still
>> available (which was not clearly stated). (Combination of much data to
>> copy and a very sharp timeout).
>
> Can you say more about what you see/understand with nonblocking mode.
> I don't understand what you mean here (and it doesn't fit with what I
> am seeing on testing). Nonblocking mode should, I believe, always mean
> an immediate return, regardless of any timeout.

It's just cosmetics really, now they state that:
"
A nonblocking call reads as many messages as are available (up to the 
limit specified by vlen) and returns immediately.
"

Suppose that you are operating in non-blocking mode, the timeout is set 
to one nanosecond (yeah, living on the edge), and vlen is an insane 
large number (say a thousand) whilst assuming that data is available to 
be received. The text from the manpage says that you will return if the 
available data is depleted or if you have read 'vlen' buffers. So it 
means there's a 'faster than timeout' possible.

What the kernel implementation actually does (simplified, and ignoring 
WAITFORONE) is:

while(datagrams < vlen) {
   err = recvmsg()
   if (err) break;
   if (timeout) break;
   datagrams++
}

Both in non-blocking/blocking mode, and I think the manpage should make 
the three possible exit scenario (vlen, timeout, err) clear in both 
blocking and non-blocking mode.

gr
E.

-- 
Elie De Brauwer

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html