[PATCH 0/4] updates for the io_*.2 man pages

[PATCH 0/4] updates for the io_*.2 man pages

[Jeff Moyer]

Hi,

Sorry about the botched send yesterday.  I've made the following changes
after reviewing the io*.2 man pages.  I am 100% open to discussion on
the changes.

Cheers,
Jeff

[PATCH 1/4] io_cancel.2: fix up the description
[PATCH 2/4] io_destroy.2: fix up the description
[PATCH 3/4] io_getevents.2: timeout will not be updated
[PATCH 4/4] io_setup.2: clarify nr_events
--
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 1/4] io_cancel.2: fix up the description

[Jeff Moyer]

The description for this sytem call was a bit inaccurate.  Cyril
still takes issue with my wording, so this is up for further
word-smithing, I think.  I'm open to suggestions.

Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/io_cancel.2 |    8 ++++----
 1 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index 0f974ed..6adddf3 100644
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -26,10 +26,10 @@ attempts to cancel an asynchronous I/O operation previously submitted with
 .BR io_submit (2).
 The
 .I ctx_id
-argument is the AIO context ID of the operation to be canceled.
-If the AIO context is found, the event will be canceled and then copied
-into the memory pointed to by \fIresult\fP without being placed
-into the completion queue.
+argument is the AIO context ID into which the operation was submitted.
+If the operation is successfully canceled, the event will be copied into
+the memory pointed to by \fIresult\fP without being placed into the
+completion queue.
 .SH RETURN VALUE
 On success,
 .BR io_cancel ()
-- 
1.7.1

--
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 2/4] io_destroy.2: fix up the description

[Jeff Moyer]

The description was rather vague, citing a "list of I/O contexts" and
stating that it "can" cancel outstanding requests.  This update makes
things more concrete so that a reader knows exactly what's going on.

Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/io_destroy.2 |    9 +++------
 1 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index 26a84f3..ea318bd 100644
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -21,12 +21,9 @@ There is no glibc wrapper for this system call; see NOTES.
 The
 .BR io_destroy ()
 system call
-removes the asynchronous I/O context specified by
-.I ctx_id
-from the list of
-I/O contexts and then destroys it.
-It can also cancel any outstanding asynchronous I/O
-actions on \fIctx_id\fP and block on completion.
+will attempt to cancel all outstanding asynchronous I/O operations
+against \fIctx_id\fP, will block on the completion of all operations
+that could not be cancelled, and will destroy the the \fIctx_id\fP.
 .SH RETURN VALUE
 On success,
 .BR io_destroy ()
-- 
1.7.1

--
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 3/4] io_getevents.2: timeout will not be updated

[Jeff Moyer]

I looked back through the kernel code, and the timeout was never updated
in any case.  I've submitted a patch upstream to change the comment
above io_getevents.

Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/io_getevents.2 |    3 +--
 1 files changed, 1 insertions(+), 2 deletions(-)

diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index 34ecd4a..72317c3 100644
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -30,8 +30,7 @@ specified by \fIctx_id\fP.
 The \fItimeout\fP argument specifies the amount of time to wait for events,
 where a NULL timeout waits until at least \fImin_nr\fP events
 have been seen.
-Note that \fItimeout\fP is relative and will be updated if not NULL
-and the operation blocks.
+Note that \fItimeout\fP is relative.
 .SH RETURN VALUE
 On success,
 .BR io_getevents ()
-- 
1.7.1

--
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 4/4] io_setup.2: clarify nr_events

[Jeff Moyer]

nr_events is technically the number of completion events that can
be stored in the completion ring.  The wording of the man page:
  "capable of receiving at least nr_events"
seems dubious to me, only because I worry that folks might interpret
that to mean nr_events total, instead of nr_events concurrently.

Further, I've added information on where to find the per-user limit
on nr_events, /proc/sys/fs/aio-max-nr.  Let me know if you think that
is not relevent.

Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
---
 man2/io_setup.2 |    5 +++--
 1 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 2a541bf..8527b80 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
 The
 .BR io_setup ()
 system call
-creates an asynchronous I/O context capable of receiving
+creates an asynchronous I/O context capable of concurrently processing
 at least \fInr_events\fP.
 The
 .I ctx_idp
@@ -37,7 +37,8 @@ For the failure return, see NOTES.
 .SH ERRORS
 .TP
 .B EAGAIN
-The specified \fInr_events\fP exceeds the user's limit of available events.
+The specified \fInr_events\fP exceeds the user's limit of available events,
+as defined in /proc/sys/fs/aio-max-nr.
 .TP
 .B EFAULT
 An invalid pointer is passed for \fIctx_idp\fP.
-- 
1.7.1

--
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 3/4] io_getevents.2: timeout will not be updated

[Michael Kerrisk (man-pages)]

On Thu, Apr 4, 2013 at 9:36 PM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> I looked back through the kernel code, and the timeout was never updated
> in any case.  I've submitted a patch upstream to change the comment
> above io_getevents.

Thanks Jeff. I councur (but it would have been good also to add me to
the CC of that patch, so I could track the discussion). Patch applied.

Cheers,

Michael



> Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/io_getevents.2 |    3 +--
>  1 files changed, 1 insertions(+), 2 deletions(-)
>
> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
> index 34ecd4a..72317c3 100644
> --- a/man2/io_getevents.2
> +++ b/man2/io_getevents.2
> @@ -30,8 +30,7 @@ specified by \fIctx_id\fP.
>  The \fItimeout\fP argument specifies the amount of time to wait for events,
>  where a NULL timeout waits until at least \fImin_nr\fP events
>  have been seen.
> -Note that \fItimeout\fP is relative and will be updated if not NULL
> -and the operation blocks.
> +Note that \fItimeout\fP is relative.
>  .SH RETURN VALUE
>  On success,
>  .BR io_getevents ()
> --
> 1.7.1
>



--
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 4/4] io_setup.2: clarify nr_events

[Michael Kerrisk (man-pages)]

On Thu, Apr 4, 2013 at 9:36 PM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> nr_events is technically the number of completion events that can
> be stored in the completion ring.  The wording of the man page:
>   "capable of receiving at least nr_events"
> seems dubious to me, only because I worry that folks might interpret
> that to mean nr_events total, instead of nr_events concurrently.
>
> Further, I've added information on where to find the per-user limit
> on nr_events, /proc/sys/fs/aio-max-nr.  Let me know if you think that
> is not relevent.

All looks good to me. Applied.

Cheers,

Michael


> Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/io_setup.2 |    5 +++--
>  1 files changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index 2a541bf..8527b80 100644
> --- a/man2/io_setup.2
> +++ b/man2/io_setup.2
> @@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
>  The
>  .BR io_setup ()
>  system call
> -creates an asynchronous I/O context capable of receiving
> +creates an asynchronous I/O context capable of concurrently processing
>  at least \fInr_events\fP.
>  The
>  .I ctx_idp
> @@ -37,7 +37,8 @@ For the failure return, see NOTES.
>  .SH ERRORS
>  .TP
>  .B EAGAIN
> -The specified \fInr_events\fP exceeds the user's limit of available events.
> +The specified \fInr_events\fP exceeds the user's limit of available events,
> +as defined in /proc/sys/fs/aio-max-nr.
>  .TP
>  .B EFAULT
>  An invalid pointer is passed for \fIctx_idp\fP.
> --
> 1.7.1
>



--
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 2/4] io_destroy.2: fix up the description

[Michael Kerrisk (man-pages)]

Hi Jeff,

On Thu, Apr 4, 2013 at 9:36 PM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> The description was rather vague, citing a "list of I/O contexts" and
> stating that it "can" cancel outstanding requests.  This update makes
> things more concrete so that a reader knows exactly what's going on.

Thanks. Applied.

Cheers,

Michael


> Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/io_destroy.2 |    9 +++------
>  1 files changed, 3 insertions(+), 6 deletions(-)
>
> diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
> index 26a84f3..ea318bd 100644
> --- a/man2/io_destroy.2
> +++ b/man2/io_destroy.2
> @@ -21,12 +21,9 @@ There is no glibc wrapper for this system call; see NOTES.
>  The
>  .BR io_destroy ()
>  system call
> -removes the asynchronous I/O context specified by
> -.I ctx_id
> -from the list of
> -I/O contexts and then destroys it.
> -It can also cancel any outstanding asynchronous I/O
> -actions on \fIctx_id\fP and block on completion.
> +will attempt to cancel all outstanding asynchronous I/O operations
> +against \fIctx_id\fP, will block on the completion of all operations
> +that could not be cancelled, and will destroy the the \fIctx_id\fP.
>  .SH RETURN VALUE
>  On success,
>  .BR io_destroy ()
> --
> 1.7.1
>



--
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 1/4] io_cancel.2: fix up the description

[Michael Kerrisk (man-pages)]

On Thu, Apr 4, 2013 at 9:36 PM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> The description for this sytem call was a bit inaccurate.  Cyril
> still takes issue with my wording, so this is up for further
> word-smithing, I think.  I'm open to suggestions.

Cyril, do you have any comment?

Thanks,

Michael


> Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> ---
>  man2/io_cancel.2 |    8 ++++----
>  1 files changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> index 0f974ed..6adddf3 100644
> --- a/man2/io_cancel.2
> +++ b/man2/io_cancel.2
> @@ -26,10 +26,10 @@ attempts to cancel an asynchronous I/O operation previously submitted with
>  .BR io_submit (2).
>  The
>  .I ctx_id
> -argument is the AIO context ID of the operation to be canceled.
> -If the AIO context is found, the event will be canceled and then copied
> -into the memory pointed to by \fIresult\fP without being placed
> -into the completion queue.
> +argument is the AIO context ID into which the operation was submitted.
> +If the operation is successfully canceled, the event will be copied into
> +the memory pointed to by \fIresult\fP without being placed into the
> +completion queue.
>  .SH RETURN VALUE
>  On success,
>  .BR io_cancel ()
> --
> 1.7.1
>



--
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 1/4] io_cancel.2: fix up the description

[chrubis-AlSwsSmVLrQ]

Hi!
> > The description for this sytem call was a bit inaccurate.  Cyril
> > still takes issue with my wording, so this is up for further
> > word-smithing, I think.  I'm open to suggestions.
> 
> Cyril, do you have any comment?

It is no big deal but I think that the sentence could be a little clearer
with explicitly stating that the ctx_id is aio context and the iocb
describes the operation to be canceled. Something like:

The
.I iocb
describes the operation to be canceled and the
.I ctx_id
is aio context the operation was submitted to.

> > Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> > ---
> >  man2/io_cancel.2 |    8 ++++----
> >  1 files changed, 4 insertions(+), 4 deletions(-)
> >
> > diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
> > index 0f974ed..6adddf3 100644
> > --- a/man2/io_cancel.2
> > +++ b/man2/io_cancel.2
> > @@ -26,10 +26,10 @@ attempts to cancel an asynchronous I/O operation previously submitted with
> >  .BR io_submit (2).
> >  The
> >  .I ctx_id
> > -argument is the AIO context ID of the operation to be canceled.
> > -If the AIO context is found, the event will be canceled and then copied
> > -into the memory pointed to by \fIresult\fP without being placed
> > -into the completion queue.
> > +argument is the AIO context ID into which the operation was submitted.
> > +If the operation is successfully canceled, the event will be copied into
> > +the memory pointed to by \fIresult\fP without being placed into the
> > +completion queue.
> >  .SH RETURN VALUE
> >  On success,
> >  .BR io_cancel ()
> > --
> > 1.7.1
> >
> 
> 
> 
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Author of "The Linux Programming Interface"; http://man7.org/tlpi/

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 1/4] io_cancel.2: fix up the description

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
>> > The description for this sytem call was a bit inaccurate.  Cyril
>> > still takes issue with my wording, so this is up for further
>> > word-smithing, I think.  I'm open to suggestions.
>> 
>> Cyril, do you have any comment?
>
> It is no big deal but I think that the sentence could be a little clearer
> with explicitly stating that the ctx_id is aio context and the iocb
> describes the operation to be canceled. Something like:
>
> The
> .I iocb
> describes the operation to be canceled and the
> .I ctx_id
> is aio context the operation was submitted to.

I agree that this is better.  Thanks Cyril!

-Jeff
--
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 1/4] io_cancel.2: fix up the description

[Michael Kerrisk (man-pages)]

On Wed, Apr 10, 2013 at 3:59 PM, Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> wrote:
> chrubis-AlSwsSmVLrQ@public.gmane.org writes:
>
>> Hi!
>>> > The description for this sytem call was a bit inaccurate.  Cyril
>>> > still takes issue with my wording, so this is up for further
>>> > word-smithing, I think.  I'm open to suggestions.
>>>
>>> Cyril, do you have any comment?
>>
>> It is no big deal but I think that the sentence could be a little clearer
>> with explicitly stating that the ctx_id is aio context and the iocb
>> describes the operation to be canceled. Something like:
>>
>> The
>> .I iocb
>> describes the operation to be canceled and the
>> .I ctx_id
>> is aio context the operation was submitted to.
>
> I agree that this is better.  Thanks Cyril!


So, in the end, I have

       The  iocb  argument  describes the operation to be canceled
       and the ctx_id argument is the AIO  context  to  which  the
       operation  was submitted.

Okay?

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 1/4] io_cancel.2: fix up the description

[chrubis-AlSwsSmVLrQ]

Hi!
> >> It is no big deal but I think that the sentence could be a little clearer
> >> with explicitly stating that the ctx_id is aio context and the iocb
> >> describes the operation to be canceled. Something like:
> >>
> >> The
> >> .I iocb
> >> describes the operation to be canceled and the
> >> .I ctx_id
> >> is aio context the operation was submitted to.
> >
> > I agree that this is better.  Thanks Cyril!
> 
> 
> So, in the end, I have
> 
>        The  iocb  argument  describes the operation to be canceled
>        and the ctx_id argument is the AIO  context  to  which  the
>        operation  was submitted.
> 
> Okay?

Okay with me.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 1/4] io_cancel.2: fix up the description

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
>> >> It is no big deal but I think that the sentence could be a little clearer
>> >> with explicitly stating that the ctx_id is aio context and the iocb
>> >> describes the operation to be canceled. Something like:
>> >>
>> >> The
>> >> .I iocb
>> >> describes the operation to be canceled and the
>> >> .I ctx_id
>> >> is aio context the operation was submitted to.
>> >
>> > I agree that this is better.  Thanks Cyril!
>> 
>> 
>> So, in the end, I have
>> 
>>        The  iocb  argument  describes the operation to be canceled
>>        and the ctx_id argument is the AIO  context  to  which  the
>>        operation  was submitted.
>> 
>> Okay?
>
> Okay with me.

Okay with me, too.

Cheers,
Jeff
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
> > Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> > ---
> >  man2/io_setup.2 |    5 +++--
> >  1 files changed, 3 insertions(+), 2 deletions(-)
> >
> > diff --git a/man2/io_setup.2 b/man2/io_setup.2
> > index 2a541bf..8527b80 100644
> > --- a/man2/io_setup.2
> > +++ b/man2/io_setup.2
> > @@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
> >  The
> >  .BR io_setup ()
> >  system call
> > -creates an asynchronous I/O context capable of receiving
> > +creates an asynchronous I/O context capable of concurrently processing
> >  at least \fInr_events\fP.
> >  The
> >  .I ctx_idp
> > @@ -37,7 +37,8 @@ For the failure return, see NOTES.
> >  .SH ERRORS
> >  .TP
> >  .B EAGAIN
> > -The specified \fInr_events\fP exceeds the user's limit of available events.
> > +The specified \fInr_events\fP exceeds the user's limit of available events,
> > +as defined in /proc/sys/fs/aio-max-nr.
> >  .TP
> >  .B EFAULT
> >  An invalid pointer is passed for \fIctx_idp\fP.

I've pulled the man pages git and started to work on the aio manpages
and noticed that there is (for some strange reason) double 'of' added by
this patch, see trivial patch to fix that bellow.

diff --git a/man2/io_setup.2 b/man2/io_setup.2
index 81b9a8b..549495a 100644
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
 The
 .BR io_setup ()
 system call
-creates an asynchronous I/O context capable of of concurrently processing
+creates an asynchronous I/O context capable of concurrently processing
 at least \fInr_events\fP.
 The
 .I ctx_idp

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
Looking carefully at the io_setup.2 man page it says:

...
The  io_setup() system call creates an asynchronous I/O context capable
of concurrently processing at least nr_events.
...
                            ^
			    The 'at least' caught my eye, as it is it
			    may suggest that the nr_events is low limit
			    on the number of events.


Wouldn't be 'at most' more appropriate here? Quick look in the kernel
sources suggest that it allocates buffers for nr_events elements.

Or am I missing something?

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 4/4] io_setup.2: clarify nr_events

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
> Looking carefully at the io_setup.2 man page it says:
>
> ...
> The  io_setup() system call creates an asynchronous I/O context capable
> of concurrently processing at least nr_events.
> ...
>                             ^
> 			    The 'at least' caught my eye, as it is it
> 			    may suggest that the nr_events is low limit
> 			    on the number of events.
>
>
> Wouldn't be 'at most' more appropriate here? Quick look in the kernel
> sources suggest that it allocates buffers for nr_events elements.
>
> Or am I missing something?

When the kernel ring buffer is setup, it is created in page size
chunks, and nr_events is rounded up:

        /* Compensate for the ring buffer's head/tail overlap entry */
        nr_events += 2; /* 1 is required, 2 for good luck */

        size = sizeof(struct aio_ring);
        size += sizeof(struct io_event) * nr_events;
        nr_pages = (size + PAGE_SIZE-1) >> PAGE_SHIFT;

        if (nr_pages < 0)
                return -EINVAL;

        nr_events = (PAGE_SIZE * nr_pages - sizeof(struct aio_ring)) / sizeof(struct io_event);

Cheers,
Jeff
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
> > Looking carefully at the io_setup.2 man page it says:
> >
> > ...
> > The  io_setup() system call creates an asynchronous I/O context capable
> > of concurrently processing at least nr_events.
> > ...
> >                             ^
> > 			    The 'at least' caught my eye, as it is it
> > 			    may suggest that the nr_events is low limit
> > 			    on the number of events.
> >
> >
> > Wouldn't be 'at most' more appropriate here? Quick look in the kernel
> > sources suggest that it allocates buffers for nr_events elements.
> >
> > Or am I missing something?
> 
> When the kernel ring buffer is setup, it is created in page size
> chunks, and nr_events is rounded up:
> 
>         /* Compensate for the ring buffer's head/tail overlap entry */
>         nr_events += 2; /* 1 is required, 2 for good luck */
> 
>         size = sizeof(struct aio_ring);
>         size += sizeof(struct io_event) * nr_events;
>         nr_pages = (size + PAGE_SIZE-1) >> PAGE_SHIFT;
> 
>         if (nr_pages < 0)
>                 return -EINVAL;
> 
>         nr_events = (PAGE_SIZE * nr_pages - sizeof(struct aio_ring)) / sizeof(struct io_event);

Ah, now it all makes sense.

And I'm thinking if it is worth of adding more clear description.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 4/4] io_setup.2: clarify nr_events

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> Hi!
>> > Looking carefully at the io_setup.2 man page it says:
>> >
>> > ...
>> > The  io_setup() system call creates an asynchronous I/O context capable
>> > of concurrently processing at least nr_events.
>> > ...
>> >                             ^
>> > 			    The 'at least' caught my eye, as it is it
>> > 			    may suggest that the nr_events is low limit
>> > 			    on the number of events.
>> >
>> >
>> > Wouldn't be 'at most' more appropriate here? Quick look in the kernel
>> > sources suggest that it allocates buffers for nr_events elements.
>> >
>> > Or am I missing something?
>> 
>> When the kernel ring buffer is setup, it is created in page size
>> chunks, and nr_events is rounded up:
>> 
>>         /* Compensate for the ring buffer's head/tail overlap entry */
>>         nr_events += 2; /* 1 is required, 2 for good luck */
>> 
>>         size = sizeof(struct aio_ring);
>>         size += sizeof(struct io_event) * nr_events;
>>         nr_pages = (size + PAGE_SIZE-1) >> PAGE_SHIFT;
>> 
>>         if (nr_pages < 0)
>>                 return -EINVAL;
>> 
>>         nr_events = (PAGE_SIZE * nr_pages - sizeof(struct aio_ring)) / sizeof(struct io_event);
>
> Ah, now it all makes sense.
>
> And I'm thinking if it is worth of adding more clear description.

I don't think so, since it's an implementation detail and subject to
change.

Cheers,
Jeff
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
> >> When the kernel ring buffer is setup, it is created in page size
> >> chunks, and nr_events is rounded up:
> >> 
> >>         /* Compensate for the ring buffer's head/tail overlap entry */
> >>         nr_events += 2; /* 1 is required, 2 for good luck */
> >> 
> >>         size = sizeof(struct aio_ring);
> >>         size += sizeof(struct io_event) * nr_events;
> >>         nr_pages = (size + PAGE_SIZE-1) >> PAGE_SHIFT;
> >> 
> >>         if (nr_pages < 0)
> >>                 return -EINVAL;
> >> 
> >>         nr_events = (PAGE_SIZE * nr_pages - sizeof(struct aio_ring)) / sizeof(struct io_event);
> >
> > Ah, now it all makes sense.
> >
> > And I'm thinking if it is worth of adding more clear description.
> 
> I don't think so, since it's an implementation detail and subject to
> change.

That is for sure, but I would like to advice the user of the interface
that nr_events is the maximum that could be expected to portably work.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
> >> > Looking carefully at the io_setup.2 man page it says:
> >> >
> >> > ...
> >> > The  io_setup() system call creates an asynchronous I/O context capable
> >> > of concurrently processing at least nr_events.
> >> > ...
> >> >                             ^
> >> > 			    The 'at least' caught my eye, as it is it
> >> > 			    may suggest that the nr_events is low limit
> >> > 			    on the number of events.
> >> >
> >> >
> >> > Wouldn't be 'at most' more appropriate here? Quick look in the kernel
> >> > sources suggest that it allocates buffers for nr_events elements.
> >> >
> >> > Or am I missing something?
> >> 
> >> When the kernel ring buffer is setup, it is created in page size
> >> chunks, and nr_events is rounded up:
> >> 
> >>         /* Compensate for the ring buffer's head/tail overlap entry */
> >>         nr_events += 2; /* 1 is required, 2 for good luck */
> >> 
> >>         size = sizeof(struct aio_ring);
> >>         size += sizeof(struct io_event) * nr_events;
> >>         nr_pages = (size + PAGE_SIZE-1) >> PAGE_SHIFT;
> >> 
> >>         if (nr_pages < 0)
> >>                 return -EINVAL;
> >> 
> >>         nr_events = (PAGE_SIZE * nr_pages - sizeof(struct aio_ring)) / sizeof(struct io_event);
> >
> > Ah, now it all makes sense.
> >
> > And I'm thinking if it is worth of adding more clear description.
> 
> I don't think so, since it's an implementation detail and subject to
> change.

What about this wording:

The io_setup() system call creates an asynchronous I/O context suitable
for concurrently processing nr_events operations.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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 4/4] io_setup.2: clarify nr_events

[Jeff Moyer]

chrubis-AlSwsSmVLrQ@public.gmane.org writes:

> What about this wording:
>
> The io_setup() system call creates an asynchronous I/O context suitable
> for concurrently processing nr_events operations.

That is fine with me.

Cheers,
Jeff
--
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 4/4] io_setup.2: clarify nr_events

[chrubis-AlSwsSmVLrQ]

Hi!
> > > Signed-off-by: Jeff Moyer <jmoyer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> > > ---
> > >  man2/io_setup.2 |    5 +++--
> > >  1 files changed, 3 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/man2/io_setup.2 b/man2/io_setup.2
> > > index 2a541bf..8527b80 100644
> > > --- a/man2/io_setup.2
> > > +++ b/man2/io_setup.2
> > > @@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
> > >  The
> > >  .BR io_setup ()
> > >  system call
> > > -creates an asynchronous I/O context capable of receiving
> > > +creates an asynchronous I/O context capable of concurrently processing
> > >  at least \fInr_events\fP.
> > >  The
> > >  .I ctx_idp
> > > @@ -37,7 +37,8 @@ For the failure return, see NOTES.
> > >  .SH ERRORS
> > >  .TP
> > >  .B EAGAIN
> > > -The specified \fInr_events\fP exceeds the user's limit of available events.
> > > +The specified \fInr_events\fP exceeds the user's limit of available events,
> > > +as defined in /proc/sys/fs/aio-max-nr.
> > >  .TP
> > >  .B EFAULT
> > >  An invalid pointer is passed for \fIctx_idp\fP.
> 
> I've pulled the man pages git and started to work on the aio manpages
> and noticed that there is (for some strange reason) double 'of' added by
> this patch, see trivial patch to fix that bellow.
> 
> diff --git a/man2/io_setup.2 b/man2/io_setup.2
> index 81b9a8b..549495a 100644
> --- a/man2/io_setup.2
> +++ b/man2/io_setup.2
> @@ -21,7 +21,7 @@ There is no glibc wrapper for this system call; see NOTES.
>  The
>  .BR io_setup ()
>  system call
> -creates an asynchronous I/O context capable of of concurrently processing
> +creates an asynchronous I/O context capable of concurrently processing
>  at least \fInr_events\fP.
>  The
>  .I ctx_idp

Ping.

-- 
Cyril Hrubis
chrubis-AlSwsSmVLrQ@public.gmane.org
--
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