Browse code

Windows: Revendor HCSShim with godoc

Signed-off-by: John Howard <John.Howard@microsoft.com>

John Howard authored on 2015/08/28 07:46:00
Showing 22 changed files
... ...
@@ -14,7 +14,7 @@ clone git github.com/gorilla/context 14f550f51a
14 14
 clone git github.com/gorilla/mux e444e69cbd
15 15
 clone git github.com/kr/pty 5cf931ef8f
16 16
 clone git github.com/mattn/go-sqlite3 b4142c444a8941d0d92b0b7103a24df9cd815e42
17
-clone git github.com/microsoft/hcsshim da093dac579302d7b413696b96dec0b5e1bce8d4
17
+clone git github.com/microsoft/hcsshim 7f646aa6b26bcf90caee91e93cde4a80d0d8a83e
18 18
 clone git github.com/mistifyio/go-zfs v2.1.1
19 19
 clone git github.com/tchap/go-patricia v2.1.0
20 20
 clone git golang.org/x/net 3cffabab72adf04f8e3b01c5baf775361837b5fe https://github.com/golang/net.git
... ...
@@ -8,6 +8,10 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// ActivateLayer will find the layer with the given id and mount it's filesystem.
12
+// For a read/write layer, the mounted filesystem will appear as a volume on the
13
+// host, while a read-only layer is generally expected to be a no-op.
14
+// An activated layer must later be deactivated via DeactivateLayer.
11 15
 func ActivateLayer(info DriverInfo, id string) error {
12 16
 	title := "hcsshim::ActivateLayer "
13 17
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
... ...
@@ -8,6 +8,10 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// CopyLayer performs a commit of the srcId (which is expected to be a read-write
12
+// layer) into a new read-only layer at dstId.  This requires the full list of
13
+// on-disk paths to parent layers, provided in parentLayerPaths, in order to
14
+// complete the commit.
11 15
 func CopyLayer(info DriverInfo, srcId, dstId string, parentLayerPaths []string) error {
12 16
 	title := "hcsshim::CopyLayer "
13 17
 	logrus.Debugf(title+"srcId %s dstId", srcId, dstId)
... ...
@@ -8,7 +8,9 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
-// CreateComputeSystem creates a container
11
+// CreateComputeSystem creates a container, initializing its configuration in
12
+// the Host Compute Service such that it can be started by a call to the
13
+// StartComputeSystem method.
12 14
 func CreateComputeSystem(id string, configuration string) error {
13 15
 
14 16
 	title := "HCSShim::CreateComputeSystem"
... ...
@@ -8,6 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// CreateLayer creates a new, empty, read-only layer on the filesystem based on
12
+// the parent layer provided.
11 13
 func CreateLayer(info DriverInfo, id, parent string) error {
12 14
 	title := "hcsshim::CreateLayer "
13 15
 	logrus.Debugf(title+"Flavour %s ID %s parent %s", info.Flavour, id, parent)
... ...
@@ -11,7 +11,7 @@ import (
11 11
 	"github.com/Sirupsen/logrus"
12 12
 )
13 13
 
14
-// processParameters is use to both the input of CreateProcessInComputeSystem
14
+// CreateProcessParams is used as both the input of CreateProcessInComputeSystem
15 15
 // and to convert the parameters to JSON for passing onto the HCS
16 16
 type CreateProcessParams struct {
17 17
 	ApplicationName  string
... ...
@@ -8,6 +8,10 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// CreateSandboxLayer creates and populates new read-write layer for use by a container.
12
+// This requires both the id of the direct parent layer, as well as the full list
13
+// of paths to all parent layers up to the base (and including the direct parent
14
+// whose id was provided).
11 15
 func CreateSandboxLayer(info DriverInfo, layerId, parentId string, parentLayerPaths []string) error {
12 16
 	title := "hcsshim::CreateSandboxLayer "
13 17
 	logrus.Debugf(title+"layerId %s parentId %s", layerId, parentId)
... ...
@@ -8,6 +8,7 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// DeactivateLayer will dismount a layer that was mounted via ActivateLayer.
11 12
 func DeactivateLayer(info DriverInfo, id string) error {
12 13
 	title := "hcsshim::DeactivateLayer "
13 14
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
... ...
@@ -8,6 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// DestroyLayer will remove the on-disk files representing the layer with the given
12
+// id, including that layer's containing folder, if any.
11 13
 func DestroyLayer(info DriverInfo, id string) error {
12 14
 	title := "hcsshim::DestroyLayer "
13 15
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
... ...
@@ -8,6 +8,11 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// ExportLayer will create a folder at exportFolderPath and fill that folder with
12
+// the transport format version of the layer identified by layerId. This transport
13
+// format includes any metadata required for later importing the layer (using
14
+// ImportLayer), and requires the full list of parent layer paths in order to
15
+// perform the export.
11 16
 func ExportLayer(info DriverInfo, layerId string, exportFolderPath string, parentLayerPaths []string) error {
12 17
 	title := "hcsshim::ExportLayer "
13 18
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, exportFolderPath)
... ...
@@ -8,6 +8,10 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// GetLayerMountPath will look for a mounted layer with the given id and return
12
+// the path at which that layer can be accessed.  This path may be a volume path
13
+// if the layer is a mounted read-write layer, otherwise it is expected to be the
14
+// folder path at which the layer is stored.
11 15
 func GetLayerMountPath(info DriverInfo, id string) (string, error) {
12 16
 	title := "hcsshim::GetLayerMountPath "
13 17
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
... ...
@@ -8,6 +8,9 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// GetSharedBaseImages will enumerate the images stored in the common central
12
+// image store and return descriptive info about those images for the purpose
13
+// of registering them with the graphdriver, graph, and tagstore.
11 14
 func GetSharedBaseImages() (imageData string, err error) {
12 15
 	title := "hcsshim::GetSharedBaseImages "
13 16
 
... ...
@@ -8,6 +8,10 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// ImportLayer will take the contents of the folder at importFolderPath and import
12
+// that into a layer with the id layerId.  Note that in order to correctly populate
13
+// the layer and interperet the transport format, all parent layers must already
14
+// be present on the system at the paths provided in parentLayerPaths.
11 15
 func ImportLayer(info DriverInfo, layerId string, importFolderPath string, parentLayerPaths []string) error {
12 16
 	title := "hcsshim::ImportLayer "
13 17
 	logrus.Debugf(title+"flavour %d layerId %s folder %s", info.Flavour, layerId, importFolderPath)
... ...
@@ -8,6 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// LayerExists will return true if a layer with the given id exists and is known
12
+// to the system.
11 13
 func LayerExists(info DriverInfo, id string) (bool, error) {
12 14
 	title := "hcsshim::LayerExists "
13 15
 	logrus.Debugf(title+"Flavour %s ID %s", info.Flavour, id)
... ...
@@ -8,6 +8,9 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// NameToGuid converts the given string into a GUID using the algorithm in the
12
+// Host Compute Service, ensuring GUIDs generated with the same string are common
13
+// across all clients.
11 14
 func NameToGuid(name string) (id GUID, err error) {
12 15
 	title := "hcsshim::NameToGuid "
13 16
 	logrus.Debugf(title+"Name %s", name)
... ...
@@ -8,6 +8,11 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// PrepareLayer finds a mounted read-write layer matching layerId and enables the
12
+// the filesystem filter for use on that layer.  This requires the paths to all
13
+// parent layers, and is necessary in order to view or interact with the layer
14
+// as an actual filesystem (reading and writing files, creating directories, etc).
15
+// Disabling the filter must be done via UnprepareLayer.
11 16
 func PrepareLayer(info DriverInfo, layerId string, parentLayerPaths []string) error {
12 17
 	title := "hcsshim::PrepareLayer "
13 18
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)
... ...
@@ -8,6 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// ResizeConsoleInComputeSystem updates the height and width of the console
12
+// session for the process with the given id in the container with the given id.
11 13
 func ResizeConsoleInComputeSystem(id string, processid uint32, h, w int) error {
12 14
 
13 15
 	title := "HCSShim::ResizeConsoleInComputeSystem"
... ...
@@ -8,7 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
-// ShutdownComputeSystem shuts down a container
11
+// ShutdownComputeSystem shuts down a container by requesting a shutdown within
12
+// the container operating system.
12 13
 func ShutdownComputeSystem(id string) error {
13 14
 
14 15
 	var title = "HCSShim::ShutdownComputeSystem"
... ...
@@ -8,7 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
-// StartComputeSystem starts a container
11
+// StartComputeSystem starts a container that has previously been created via
12
+// CreateComputeSystem.
12 13
 func StartComputeSystem(id string) error {
13 14
 
14 15
 	title := "HCSShim::StartComputeSystem"
... ...
@@ -8,7 +8,7 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
-// TerminateComputeSystem force terminates a container
11
+// TerminateComputeSystem force terminates a container.
12 12
 func TerminateComputeSystem(id string) error {
13 13
 
14 14
 	var title = "HCSShim::TerminateComputeSystem"
... ...
@@ -8,7 +8,7 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
-// TerminateProcessInComputeSystem kills a process in a running container
11
+// TerminateProcessInComputeSystem kills a process in a running container.
12 12
 func TerminateProcessInComputeSystem(id string, processid uint32) (err error) {
13 13
 
14 14
 	title := "HCSShim::TerminateProcessInComputeSystem"
... ...
@@ -8,6 +8,8 @@ import (
8 8
 	"github.com/Sirupsen/logrus"
9 9
 )
10 10
 
11
+// UnprepareLayer disables the filesystem filter for the read-write layer with
12
+// the given id.
11 13
 func UnprepareLayer(info DriverInfo, layerId string) error {
12 14
 	title := "hcsshim::UnprepareLayer "
13 15
 	logrus.Debugf(title+"flavour %d layerId %s", info.Flavour, layerId)