Re: [PATCH XEN v6 25/32] tools/libs/gnttab: Extensive updates to API documentation.

[Ian Campbell <ian.campbell@citrix.com>]

On Wed, 2015-12-09 at 17:08 +0000, Ian Campbell wrote:
> On Wed, 2015-12-09 at 16:28 +0000, Ian Jackson wrote:
> > Ian Campbell writes ("Re: [PATCH XEN v6 25/32] tools/libs/gnttab:
> > Extensive updates to API documentation."):
> > > On Wed, 2015-12-09 at 16:09 +0000, Ian Jackson wrote:
> > > > Is this actually true ?  Normally close() on an fd does not munmap
> > > > anything mmapped from the fd.
> > > 
> > > Uh yes, I was talking rubbish here, unless the drivers are more magic
> > > than
> > > I think they are.
> > > 
> > > So what is the answer? That such memory is wasted and irrecovable
> > > until
> > > exec?
> > 
> > I don't know.  What would happen if you munmapped it ?
> 
> We discussed all this IRL and concluded after much back and forth that
> there is nothing we can do here other than require a call to each relevant
> library's _close() method by callers of fork() who do not exec but who care
> about the (usually modest) resources consumed by these sorts of mappings.
> 
> The _close call after fork should be documented as potentially not actually
> achieving anything and we decided to treat this as a future bug if/when it
> has a real world impact by fixing.

Here is what I cam up with.

/*
 * Returns a handle onto the grant table driver.  Logs errors.
 *
 * Note: After fork(2) a child process must not use any opened gnttab
 * handle inherited from their parent, nor access any grant mapped
 * areas associated with that handle.
 *
 * The child must open a new handle if they want to interact with
 * gnttab.
 *
 * Calling exec(2) in a child will safely (and reliably) reclaim any
 * allocated resources via a xengnttab_handle in the parent.
 *
 * A child which does not call exec(2) may safely call
 * xengnttab_close() on a xengnttab_handle inherited from their
 * parent. This will attempt to reclaim any resources associated with
 * that handle. Note that in some implementations this reclamation may
 * not be completely effective, in this case any affected resources
 * remain allocated.
 *
 * Calling xengnttab_close() is the only safe operation on a
 * xengnttab_handle which has been inherited.
 */

I'm currently intending to write something very similar for each of the
xen*_open (gntshr, gnttab, foreignmemory, evtchn and probably call too)
functions. I don't really like repeating the same thing like this, but I
also don't really like API documentation which makes you play follow the
piece of string to the docs of other libraries to find out what is going
on.

I'm also considering whether on the _close function I should write
something to the effect that in non-forked contexts the application should
call the associated _unmap() on any active mappings before calling _close()
in order to ensure all resources have been freed. And reiterate that
calling _unmap after fork() is not safe.

Ian.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel