[PATCH v2] socket.7: add description for SO_BUSY_POLL

[PATCH v2] socket.7: add description for SO_BUSY_POLL

[Eliezer Tamir]

Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.

v2
fixed typos reported by Rasmus Villemoes

Signed-off-by: Eliezer Tamir <eliezer.tamir@linux.intel.com>
---

 man7/socket.7 |   25 +++++++++++++++++++++++++
 1 files changed, 25 insertions(+), 0 deletions(-)

diff --git a/man7/socket.7 b/man7/socket.7
index f2213eb..5edcb09 100644
--- a/man7/socket.7
+++ b/man7/socket.7
@@ -694,6 +694,31 @@ for details on control messages.
 Gets the socket type as an integer (e.g.,
 .BR SOCK_STREAM ).
 This socket option is read-only.
+.TP
+.B SO_BUSY_POLL
+Sets the approximate time in microseconds to busy poll on a blocking receive
+when there is no data. Increasing this value requires
+.BR CAP_NET_ADMIN . 
+The default for this option is controlled by the
+.I /proc/sys/net/core/busy_read
+file. 
+
+The value in the  
+.I /proc/sys/net/core/busy_poll
+file determines how long 
+.BR select (2)
+and 
+.BR poll (2)
+will busy poll when they operate on sockets with 
+.BR SO_BUSY_POLL
+set and no events to report are found.
+
+In both cases busy polling will only be done when the socket last received data
+from a network device that supports this option.
+
+While busy polling may improve latency of some applications, care must be
+taken when using it since this will increase both CPU utilization and power usage.
+
 .SS Signals
 When writing onto a connection-oriented socket that has been shut down
 (by the local or the remote end)

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Michael Kerrisk]

On 07/10/13 16:18, Eliezer Tamir wrote:
> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
> 
> v2
> fixed typos reported by Rasmus Villemoes

Eliezer,

What's the status of this feature. A quick grep seems to show
that the feature is not yet in mainline. What is the plan?

Thanks,

Michael



> Signed-off-by: Eliezer Tamir <eliezer.tamir@linux.intel.com>
> ---
> 
>  man7/socket.7 |   25 +++++++++++++++++++++++++
>  1 files changed, 25 insertions(+), 0 deletions(-)
> 
> diff --git a/man7/socket.7 b/man7/socket.7
> index f2213eb..5edcb09 100644
> --- a/man7/socket.7
> +++ b/man7/socket.7
> @@ -694,6 +694,31 @@ for details on control messages.
>  Gets the socket type as an integer (e.g.,
>  .BR SOCK_STREAM ).
>  This socket option is read-only.
> +.TP
> +.B SO_BUSY_POLL
> +Sets the approximate time in microseconds to busy poll on a blocking receive
> +when there is no data. Increasing this value requires
> +.BR CAP_NET_ADMIN . 
> +The default for this option is controlled by the
> +.I /proc/sys/net/core/busy_read
> +file. 
> +
> +The value in the  
> +.I /proc/sys/net/core/busy_poll
> +file determines how long 
> +.BR select (2)
> +and 
> +.BR poll (2)
> +will busy poll when they operate on sockets with 
> +.BR SO_BUSY_POLL
> +set and no events to report are found.
> +
> +In both cases busy polling will only be done when the socket last received data
> +from a network device that supports this option.
> +
> +While busy polling may improve latency of some applications, care must be
> +taken when using it since this will increase both CPU utilization and power usage.
> +
>  .SS Signals
>  When writing onto a connection-oriented socket that has been shut down
>  (by the local or the remote end)
> 
> 

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[David Miller]

From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Wed, 10 Jul 2013 20:03:08 +0200

> On 07/10/13 16:18, Eliezer Tamir wrote:
>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
>> 
>> v2
>> fixed typos reported by Rasmus Villemoes
> 
> Eliezer,
> 
> What's the status of this feature. A quick grep seems to show
> that the feature is not yet in mainline. What is the plan?

It's in Linus's tree.

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Michael Kerrisk (man-pages)]

On Wed, Jul 10, 2013 at 8:52 PM, David Miller <davem@davemloft.net> wrote:
> From: Michael Kerrisk <mtk.manpages@gmail.com>
> Date: Wed, 10 Jul 2013 20:03:08 +0200
>
>> On 07/10/13 16:18, Eliezer Tamir wrote:
>>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
>>>
>>> v2
>>> fixed typos reported by Rasmus Villemoes
>>
>> Eliezer,
>>
>> What's the status of this feature. A quick grep seems to show
>> that the feature is not yet in mainline. What is the plan?
>
> It's in Linus's tree.

That doesn't appear to be the case. grepping current Linus Git for
SO_BUSY_POLL yields nada. What am I missing?

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[David Miller]

From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Date: Wed, 10 Jul 2013 20:57:16 +0200

> On Wed, Jul 10, 2013 at 8:52 PM, David Miller <davem@davemloft.net> wrote:
>> From: Michael Kerrisk <mtk.manpages@gmail.com>
>> Date: Wed, 10 Jul 2013 20:03:08 +0200
>>
>>> On 07/10/13 16:18, Eliezer Tamir wrote:
>>>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
>>>>
>>>> v2
>>>> fixed typos reported by Rasmus Villemoes
>>>
>>> Eliezer,
>>>
>>> What's the status of this feature. A quick grep seems to show
>>> that the feature is not yet in mainline. What is the plan?
>>
>> It's in Linus's tree.
> 
> That doesn't appear to be the case. grepping current Linus Git for
> SO_BUSY_POLL yields nada. What am I missing?

In the same set of postings Eliezer made with this manpage patch, he
also posted kernel patches which rename the socket option to it's
final name.

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Eliezer Tamir]

On 10/07/2013 21:03, Michael Kerrisk wrote:
> On 07/10/13 16:18, Eliezer Tamir wrote:
>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
> 
> What's the status of this feature. A quick grep seems to show
> that the feature is not yet in mainline. What is the plan?

The basic code is already in Linus' tree. there were request to rename
things. The current name for the socket option is SO_LL but a patche to
rename it to SO_BUSY_POLL were sent to net-dev.

http://patchwork.ozlabs.org/patch/258065/

If you want me to notify you when the change hits Linus' tree I can do that.

-Eliezer

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Michael Kerrisk (man-pages)]

On 07/10/2013 04:18 PM, Eliezer Tamir wrote:
> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.

Long after the fact, I've applied this. Thanks, Eliezer.

Would you be willing also to write a patch for the POLL_BUSY_LOOP flag of 
poll()?

Cheers,

Michael


> v2
> fixed typos reported by Rasmus Villemoes
> 
> Signed-off-by: Eliezer Tamir <eliezer.tamir@linux.intel.com>
> ---
> 
>  man7/socket.7 |   25 +++++++++++++++++++++++++
>  1 files changed, 25 insertions(+), 0 deletions(-)
> 
> diff --git a/man7/socket.7 b/man7/socket.7
> index f2213eb..5edcb09 100644
> --- a/man7/socket.7
> +++ b/man7/socket.7
> @@ -694,6 +694,31 @@ for details on control messages.
>  Gets the socket type as an integer (e.g.,
>  .BR SOCK_STREAM ).
>  This socket option is read-only.
> +.TP
> +.B SO_BUSY_POLL
> +Sets the approximate time in microseconds to busy poll on a blocking receive
> +when there is no data. Increasing this value requires
> +.BR CAP_NET_ADMIN . 
> +The default for this option is controlled by the
> +.I /proc/sys/net/core/busy_read
> +file. 
> +
> +The value in the  
> +.I /proc/sys/net/core/busy_poll
> +file determines how long 
> +.BR select (2)
> +and 
> +.BR poll (2)
> +will busy poll when they operate on sockets with 
> +.BR SO_BUSY_POLL
> +set and no events to report are found.
> +
> +In both cases busy polling will only be done when the socket last received data
> +from a network device that supports this option.
> +
> +While busy polling may improve latency of some applications, care must be
> +taken when using it since this will increase both CPU utilization and power usage.
> +
>  .SS Signals
>  When writing onto a connection-oriented socket that has been shut down
>  (by the local or the remote end)
> 
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Eliezer Tamir]

On 20/01/2014 18:28, Michael Kerrisk (man-pages) wrote:
> On 07/10/2013 04:18 PM, Eliezer Tamir wrote:
>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
> 
> Long after the fact, I've applied this. Thanks, Eliezer.
> 
> Would you be willing also to write a patch for the POLL_BUSY_LOOP flag of 
> poll()?

Yes, Me or someone from our team will do that.

-Eliezer

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Michael Kerrisk (man-pages)]

On 20 January 2014 at 18:28, Eliezer Tamir
<eliezer.tamir@linux.intel.com> wrote:
> On 20/01/2014 18:28, Michael Kerrisk (man-pages) wrote:
>> On 07/10/2013 04:18 PM, Eliezer Tamir wrote:
>>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
>>
>> Long after the fact, I've applied this. Thanks, Eliezer.
>>
>> Would you be willing also to write a patch for the POLL_BUSY_LOOP flag of
>> poll()?
>
> Yes, Me or someone from our team will do that.

Hi Eliezer,

Could you or someone from your team send me a POLL_BUSY_LOOP doc patch?

Thanks,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v2] socket.7: add description for SO_BUSY_POLL

[Eliezer Tamir]

On 05/02/2015 15:17, Michael Kerrisk (man-pages) wrote:
> On 20 January 2014 at 18:28, Eliezer Tamir
> <eliezer.tamir@linux.intel.com> wrote:
>> On 20/01/2014 18:28, Michael Kerrisk (man-pages) wrote:
>>> On 07/10/2013 04:18 PM, Eliezer Tamir wrote:
>>>> Add description for the SO_BUSY_POLL socket option to the socket(7) manpage.
>>>
>>> Long after the fact, I've applied this. Thanks, Eliezer.
>>>
>>> Would you be willing also to write a patch for the POLL_BUSY_LOOP flag of
>>> poll()?
>>
>> Yes, Me or someone from our team will do that.
> 
> Hi Eliezer,
> 
> Could you or someone from your team send me a POLL_BUSY_LOOP doc patch?

Hi Michael,

Right now POLL_BUSY_LOOP is only used internally to control busylooping,
as a signal between sock_poll() and do_poll().
Our original intention was to expose that to the users of epoll().
The work on epoll() support is not finished yet.

I think we should not document this until we finalize epoll() support.

Thanks,
Eliezer