runc/container.go

105 lines
3.3 KiB
Go
Raw Normal View History

/*
NOTE: The API is in flux and mainly not implemented. Proceed with caution until further notice.
*/
package libcontainer
import (
"os"
"github.com/docker/libcontainer/cgroups"
"github.com/docker/libcontainer/configs"
"github.com/docker/libcontainer/network"
)
type Stats struct {
NetworkStats *network.NetworkStats `json:"network_stats,omitempty"`
CgroupStats *cgroups.Stats `json:"cgroup_stats,omitempty"`
}
// A libcontainer container object.
//
// Each container is thread-safe within the same process. Since a container can
// be destroyed by a separate process, any function may return that the container
// was not found.
type Container interface {
// Returns the ID of the container
ID() string
// Returns the current status of the container.
//
// errors:
// Systemerror - System error.
Status() (configs.Status, error)
// Returns the current config of the container.
Config() configs.Config
// Returns the PIDs inside this container. The PIDs are in the namespace of the calling process.
//
// errors:
Add rich errors to the API Add a rich Error type to the libcontainer package and use it in the API so that callers can: * Check for a specific error without depending on an error string, * Obtain the stack trace of the function or method which detected the error. The Error type provides a typed error code and a stack trace. The error code identifies the error and enables the caller to test for it without being sensitive to changes in the error text. The stack trace identifies the point at which the error was detected. The combination of error code and stack trace will enable errors to be diagnosed much more easily and with less guesswork than when raw string-based errors are used. The Error type conforms to the error interface and its Error method prints a short error message. The Detail method provides a verbose error message including the stack trace. Notes: 1. There is an unfortunate precedent in the Go standard library which uses variables to define errors. Checking for a specific error involves a string comparison and assumes the corresponding variable has not been updated. It is more robust and efficient to identify errors with integer-based types and associated constants, although errors should still include a string description for ease of use by humans. 2. It is not feasible to assign distinct types to Factory and Container error codes because common errors such as SystemError cannot be declared in two places and the names of the error codes then need to be decorated. This is less readable. Signed-off-by: Steve Powell <spowell@pivotal.io>
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
// Systemerror - System error.
//
// Some of the returned PIDs may no longer refer to processes in the Container, unless
// the Container state is PAUSED in which case every PID in the slice is valid.
Processes() ([]int, error)
// Returns statistics for the container.
//
// errors:
// ContainerDestroyed - Container no longer exists,
// Systemerror - System error.
Stats() (*Stats, error)
// Start a process inside the container. Returns the PID of the new process (in the caller process's namespace) and a channel that will return the exit status of the process whenever it dies.
//
// errors:
Add rich errors to the API Add a rich Error type to the libcontainer package and use it in the API so that callers can: * Check for a specific error without depending on an error string, * Obtain the stack trace of the function or method which detected the error. The Error type provides a typed error code and a stack trace. The error code identifies the error and enables the caller to test for it without being sensitive to changes in the error text. The stack trace identifies the point at which the error was detected. The combination of error code and stack trace will enable errors to be diagnosed much more easily and with less guesswork than when raw string-based errors are used. The Error type conforms to the error interface and its Error method prints a short error message. The Detail method provides a verbose error message including the stack trace. Notes: 1. There is an unfortunate precedent in the Go standard library which uses variables to define errors. Checking for a specific error involves a string comparison and assumes the corresponding variable has not been updated. It is more robust and efficient to identify errors with integer-based types and associated constants, although errors should still include a string description for ease of use by humans. 2. It is not feasible to assign distinct types to Factory and Container error codes because common errors such as SystemError cannot be declared in two places and the names of the error codes then need to be decorated. This is less readable. Signed-off-by: Steve Powell <spowell@pivotal.io>
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
// ConfigInvalid - config is invalid,
// ContainerPaused - Container is paused,
// Systemerror - System error.
Start(process *Process) (pid int, err error)
// Destroys the container after killing all running processes.
//
// Any event registrations are removed before the container is destroyed.
// No error is returned if the container is already destroyed.
//
// errors:
// Systemerror - System error.
Destroy() error
// If the Container state is RUNNING or PAUSING, sets the Container state to PAUSING and pauses
// the execution of any user processes. Asynchronously, when the container finished being paused the
// state is changed to PAUSED.
// If the Container state is PAUSED, do nothing.
//
// errors:
Add rich errors to the API Add a rich Error type to the libcontainer package and use it in the API so that callers can: * Check for a specific error without depending on an error string, * Obtain the stack trace of the function or method which detected the error. The Error type provides a typed error code and a stack trace. The error code identifies the error and enables the caller to test for it without being sensitive to changes in the error text. The stack trace identifies the point at which the error was detected. The combination of error code and stack trace will enable errors to be diagnosed much more easily and with less guesswork than when raw string-based errors are used. The Error type conforms to the error interface and its Error method prints a short error message. The Detail method provides a verbose error message including the stack trace. Notes: 1. There is an unfortunate precedent in the Go standard library which uses variables to define errors. Checking for a specific error involves a string comparison and assumes the corresponding variable has not been updated. It is more robust and efficient to identify errors with integer-based types and associated constants, although errors should still include a string description for ease of use by humans. 2. It is not feasible to assign distinct types to Factory and Container error codes because common errors such as SystemError cannot be declared in two places and the names of the error codes then need to be decorated. This is less readable. Signed-off-by: Steve Powell <spowell@pivotal.io>
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
// Systemerror - System error.
Pause() error
// If the Container state is PAUSED, resumes the execution of any user processes in the
// Container before setting the Container state to RUNNING.
// If the Container state is RUNNING, do nothing.
//
// errors:
Add rich errors to the API Add a rich Error type to the libcontainer package and use it in the API so that callers can: * Check for a specific error without depending on an error string, * Obtain the stack trace of the function or method which detected the error. The Error type provides a typed error code and a stack trace. The error code identifies the error and enables the caller to test for it without being sensitive to changes in the error text. The stack trace identifies the point at which the error was detected. The combination of error code and stack trace will enable errors to be diagnosed much more easily and with less guesswork than when raw string-based errors are used. The Error type conforms to the error interface and its Error method prints a short error message. The Detail method provides a verbose error message including the stack trace. Notes: 1. There is an unfortunate precedent in the Go standard library which uses variables to define errors. Checking for a specific error involves a string comparison and assumes the corresponding variable has not been updated. It is more robust and efficient to identify errors with integer-based types and associated constants, although errors should still include a string description for ease of use by humans. 2. It is not feasible to assign distinct types to Factory and Container error codes because common errors such as SystemError cannot be declared in two places and the names of the error codes then need to be decorated. This is less readable. Signed-off-by: Steve Powell <spowell@pivotal.io>
2014-09-04 07:03:41 +08:00
// ContainerDestroyed - Container no longer exists,
// Systemerror - System error.
Resume() error
// Signal sends the specified signal to the init process of the container.
//
// errors:
// ContainerDestroyed - Container no longer exists,
// ContainerPaused - Container is paused,
// Systemerror - System error.
Signal(signal os.Signal) error
// OOM returns a read-only channel signaling when the container receives an OOM notification.
//
// errors:
// Systemerror - System error.
OOM() (<-chan struct{}, error)
}