engine: Clarify comments in TaskEngine
@@ -48,10 +48,12 @@ const (
labelPrefix = "com.amazonaws.ecs."
)
-// DockerTaskEngine is an abstraction over the DockerGoClient so that
+// DockerTaskEngine is a state machine for managing a task and its containers
+// in ECS.
+//
+// DockerTaskEngine implements an abstraction over the DockerGoClient so that
// it does not have to know about tasks, only containers
-// The DockerTaskEngine interacts with docker to implement a task
-// engine
+// The DockerTaskEngine interacts with Docker to implement a TaskEngine
type DockerTaskEngine struct {
// implements TaskEngine
@@ -407,6 +409,11 @@ func (engine *DockerTaskEngine) handleDockerEvents(ctx context.Context) {
}
}
+// handleDockerEvent is the entrypoint for task modifications originating with
+// events occurring through Docker, outside the task engine itself.
+// handleDockerEvent is responsible for taking an event that correlates to a
+// container and placing it in the context of the task to which that container
+// belongs.
func (engine *DockerTaskEngine) handleDockerEvent(event DockerContainerChangeEvent) bool {
log.Debug("Handling a docker event", "event", event)
@@ -471,6 +478,7 @@ func (engine *DockerTaskEngine) AddTask(task *api.Task) error {
type transitionApplyFunc (func(*api.Task, *api.Container) DockerContainerMetadata)
+// tryApplyTransition wraps the transitionApplyFunc provided
func tryApplyTransition(task *api.Task, container *api.Container, to api.ContainerStatus, f transitionApplyFunc) DockerContainerMetadata {
return f(task, container)
}
@@ -684,6 +692,9 @@ func (engine *DockerTaskEngine) updateTask(task *api.Task, update *api.Task) {
log.Debug("Update was taken off the acs channel", "task", task.Arn, "status", updateDesiredStatus)
}
+// transitionFunctionMap provides the logic for the simple state machine of the
+// DockerTaskEngine. Each desired state maps to a function that can be called
+// to try and move the task to that desired state.
func (engine *DockerTaskEngine) transitionFunctionMap() map[api.ContainerStatus]transitionApplyFunc {
return map[api.ContainerStatus]transitionApplyFunc{
api.ContainerPulled: engine.pullContainer,
@@ -693,7 +704,8 @@ func (engine *DockerTaskEngine) transitionFunctionMap() map[api.ContainerStatus]
}
}
-// applyContainerState moves the container to the given state
+// applyContainerState moves the container to the given state by calling the
+// function defined in the transitionFunctionMap for the state
func (engine *DockerTaskEngine) applyContainerState(task *api.Task, container *api.Container, nextState api.ContainerStatus) DockerContainerMetadata {
clog := log.New("task", task, "container", container)
transitionFunction, ok := engine.transitionFunctionMap()[nextState]
@@ -712,6 +724,9 @@ func (engine *DockerTaskEngine) applyContainerState(task *api.Task, container *a
return metadata
}
+// transitionContainer calls applyContainerState, and then notifies the managed
+// task of the change. transitionContainer is called by progressContainers and
+// by handleStoppedToRunningContainerTransition.
func (engine *DockerTaskEngine) transitionContainer(task *api.Task, container *api.Container, to api.ContainerStatus) {
// Let docker events operate async so that we can continue to handle ACS / other requests
// This is safe because 'applyContainerState' will not mutate the task
