Initial version of libcontainer API.

Docker-DCO-1.1-Signed-off-by: Victor Marmol <vmarmol@google.com> (github: vmarmol)

This is an initial proposal of what a libcontainer API would look like. You can see it is in no way implemented :) This is primarily for discussion on the API, we can merge this and start working on the individual pieces one at a time.

The proposed API borrows heavily from lmctfy and libct with some changes to improve on those. Key aspects are:
- Container names as hierarchical path
- Separating Creating a container from Getting a container (the latter gets a reference to a running container)
- Containers as objects we can perform action on.

Any and all comments are welcomed :) I think the documentation on these may be a little lighter than I'd like. I can add more as it is requested.
On 19/06/2014 08:13, Victor Marmol wrote:
>
> In api.go:
>
> > +
> > +	// TODO(vmarmol): The name will definitely be a single one for cgroups (due to unified hierarchy), but the namespace
> > +	// set may not be, we need to flesh-out whether we return a set() of namespaces.
> > +	// Detect what container the specified TID (or PID) is in. The TID/PID must be in the calling processes' namespace.
> > +	Detect(tid int) (string, error)
> > +}
> > +
> > +// TODO(vmarmol): Rename Container -> ContainerSpec and LibcontainerContainer -> Container.
> > +// A libcontainer container object. Must be created by ContainerFactory.
> > +// Each container is thread-safe within the same process.
> > +type LibcontainerContainer interface {
> > +	// Returns the absolute name of this container.
> > +	Name() string
> > +
> > +	// Updates the container as per the spec. If an update fails, the container may be left in an inconsistent state.
> > +	Update(spec *Container) error
>
> Will split this update into multiple parts. It is tricky that this 
> doesn't become a call per knob. WDYT of having more specific (but not 
> just one knob) categories? For now I only have Cgroup, I can see us 
> adding for Network, Mount, and Devices.
>
I don't have a problem with a function for each settable attribute. This 
makes the specification of those functions and their error cases 
straightforward. We just need to find a good way of making the API 
readable given the potentially large number of such functions. It would 
be worth grouping these into separate "modifier" interfaces, along the 
lines you suggest, such as CgroupModifier, etc.. Rather than bundling 
all these into the top-level API, we could also have functions to return 
the particular modifier interfaces.
>
> We can also take the approach of updates being DIFFs where we only 
> update what is specified. Getting the actual spec can be done with the 
> Spec() call so no remembering should be necessary (but I also tend to 
> like DIFF updates more, as they are almost always the most common case).
>
I'd need to see a proposal as the only DIFF style APIs I've seen in the 
past haven't worked out too well.
>
> —
> Reply to this email directly or view it on GitHub 
> <https://github.com/docker/libcontainer/pull/28/files#r13955881>.
>