Page MenuHomeFreeBSD

Fix various nits in the aio operation manpages.
ClosedPublic

Authored by jhb on Aug 10 2016, 6:40 PM.

Details

Summary

Fix various nits in the aio operation manpages.

  • Avoid double use of "request" in a single sentence. Instead, describe aio_sigevent as being used to request notification of the associated operation's completion. This matches the language used to describe aio_sigevent in aio(4).
  • Rearrange prohibition on modifying buffers while requests are in flight.
  • Fix case mismatch.
  • Drop note about not using stack variables. C programmers should be able to figure out if a stack variable is safe based on the later warning about the life cycle requirements of control blocks.

Requested by: wblock (1), kib (4)
Submitted by: wblock (2)

Diff Detail

Repository
rS FreeBSD src repository - subversion
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

jhb retitled this revision from to Fix various nits in the aio operation manpages..
jhb updated this object.
jhb edited the test plan for this revision. (Show Details)
jhb added reviewers: kib, wblock.
rpokala added inline comments.
lib/libc/sys/aio_fsync.2
94 ↗(On Diff #19186)

I think

"while the request has been enqueued but has not yet completed."

reads a little clearer.

kib edited edge metadata.
This revision is now accepted and ready to land.Aug 10 2016, 7:02 PM
jhb edited edge metadata.
  • s/after/while/
  • Don't require non-changes to the buffer for fsync/mlock.
This revision now requires review to proceed.Aug 15 2016, 5:52 PM
jhb marked an inline comment as done.Aug 15 2016, 6:00 PM
jhb added inline comments.
lib/libc/sys/aio_fsync.2
94 ↗(On Diff #19186)

Could we even just say "while the request is enqueued"? If that language is sufficiently clear (i.e. not too vague) to cover the request up until it is completed, then I think it would be less of a mouthful.

lib/libc/sys/aio_mlock.2
88 ↗(On Diff #19296)

In this case, I didn't want to keep the prohibition on modifying the buffer (i.e. the memory mapped by the region being mlock'd) as modifying the data in the pages won't result in indeterminate behavior wrt mlock(). However, it's not clear if we should prohibit changes to the mapping (e.g. munmap(), mprotect(), etc.) while the request is pending?

lib/libc/sys/aio_mlock.2
88 ↗(On Diff #19296)

We should prohibit changes to mappings, since mappings are parsed at the moment the mlock() is performed. Or rather, the aio request would mlock whatever is mapped at the time of processing, rather at the time of issuing the request.

BTW, there is a difference between modifying buffers or mappings, and modifying the control block itself. The laguage above only talks about control block.

lib/libc/sys/aio_fsync.2
94 ↗(On Diff #19186)

I'm fine with "while the request is enqueued", IFF the aiocb still counts as "enqueued" after it has been dispatched but while it is still in-flight.

jhb marked an inline comment as done.
jhb edited edge metadata.
  • Fix subject/verb disagreement.
  • Use conciser "is queued" vs "has been enqueued but not yet completed"
  • Prohibit modifications of the memory mapping while queued.
kib edited edge metadata.
This revision is now accepted and ready to land.Aug 15 2016, 8:09 PM
This revision was automatically updated to reflect the committed changes.