From 9cb883ca686f496bd6af6e6bfbc6098c3281fc3f Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Wed, 28 Mar 2018 10:16:41 -0700 Subject: [PATCH] Godoc fixes (#898) Add some godoc comments for the api/agent package and some of its subpackages. --- api/agent/agent.go | 16 ++++++++-------- api/agent/doc.go | 26 ++++++++++++++++++++++++++ api/agent/drivers/doc.go | 14 ++++++++++++++ api/agent/drivers/docker/doc.go | 5 +++++ api/agent/drivers/mock/mocker.go | 1 + api/agent/lb_agent.go | 2 ++ api/agent/protocol/doc.go | 12 ++++++++++++ 7 files changed, 68 insertions(+), 8 deletions(-) create mode 100644 api/agent/doc.go create mode 100644 api/agent/drivers/doc.go create mode 100644 api/agent/drivers/docker/doc.go create mode 100644 api/agent/protocol/doc.go diff --git a/api/agent/agent.go b/api/agent/agent.go index e29e8ffce..e8eed5a55 100644 --- a/api/agent/agent.go +++ b/api/agent/agent.go @@ -43,17 +43,17 @@ import ( // TODO it would be really nice if we made the ramToken wrap the driver cookie (less brittle, // if those leak the container leaks too...) -- not the allocation, but the token.Close and cookie.Close // TODO if machine is out of ram, just timeout immediately / wait for hot slot? (discuss policy) -// + // Agent exposes an api to create calls from various parameters and then submit // those calls, it also exposes a 'safe' shutdown mechanism via its Close method. // Agent has a few roles: -// * manage the memory pool for a given server -// * manage the container lifecycle for calls (hot+cold) -// * execute calls against containers -// * invoke Start and End for each call appropriately -// * check the mq for any async calls, and submit them +// * manage the memory pool for a given server +// * manage the container lifecycle for calls (hot+cold) +// * execute calls against containers +// * invoke Start and End for each call appropriately +// * check the mq for any async calls, and submit them // -// overview: +// Overview: // Upon submission of a call, Agent will start the call's timeout timer // immediately. If the call is hot, Agent will attempt to find an active hot // container for that route, and if necessary launch another container. Cold @@ -69,7 +69,6 @@ import ( // sending any input, if hot. call.End will be called regardless of the // timeout timer's status if the call was executed, and that error returned may // be returned from Submit. - type Agent interface { // GetCall will return a Call that is executable by the Agent, which // can be built via various CallOpt's provided to the method. @@ -117,6 +116,7 @@ type agent struct { shutdown chan struct{} } +// New creates an Agent that executes functions locally as Docker containers. func New(da DataAccess) Agent { a := createAgent(da, true).(*agent) a.wg.Add(1) diff --git a/api/agent/doc.go b/api/agent/doc.go new file mode 100644 index 000000000..3a2cf979f --- /dev/null +++ b/api/agent/doc.go @@ -0,0 +1,26 @@ +// Package agent defines the Agent interface and related concepts. An agent is +// an entity that knows how to execute an Fn function. +// +// The Agent Interface +// +// The Agent interface is the heart of this package. Agent exposes an api to +// create calls from various parameters and then execute those calls. An Agent +// has a few roles: +// * manage the memory pool for a given server +// * manage the container lifecycle for calls (hot+cold) +// * execute calls against containers +// * invoke Start and End for each call appropriately +// * check the mq for any async calls, and submit them +// +// For more information about how an agent executes a call see the +// documentation on the Agent interface. +// +// Variants +// +// There are two flavors of runner, the local Docker agent and a load-balancing +// agent. To create an agent that uses Docker containers to execute calls, use +// New(). +// +// To create an agent that can load-balance across a pool of sub-agents, use +// NewLBAgent(). +package agent diff --git a/api/agent/drivers/doc.go b/api/agent/drivers/doc.go new file mode 100644 index 000000000..472c6b224 --- /dev/null +++ b/api/agent/drivers/doc.go @@ -0,0 +1,14 @@ +// Package drivers is intended as a general purpose container abstraction +// library. It abstracts across the differences between different container +// runtimes (e.g. Docker, Rkt, etc.) and provides utlities and data types that +// are common across all runtimes. +// +// Docker Driver +// +// The docker driver runs functions as Docker containers. +// +// Mock Driver +// +// The mock driver pretends to run functions but doesn't actually run them. This +// is for testing only. +package drivers diff --git a/api/agent/drivers/docker/doc.go b/api/agent/drivers/docker/doc.go new file mode 100644 index 000000000..bd303e793 --- /dev/null +++ b/api/agent/drivers/docker/doc.go @@ -0,0 +1,5 @@ +// Package docker provides a Docker driver for Fn. Provides an implementation +// of +// github.com/fnproject/fn/api/agent/drivers.Driver +// that knows how to run Docker images. +package docker diff --git a/api/agent/drivers/mock/mocker.go b/api/agent/drivers/mock/mocker.go index dfc2568d4..b4199539f 100644 --- a/api/agent/drivers/mock/mocker.go +++ b/api/agent/drivers/mock/mocker.go @@ -1,3 +1,4 @@ +// Package mock provides a fake Driver implementation that is only used for testing. package mock import ( diff --git a/api/agent/lb_agent.go b/api/agent/lb_agent.go index 689ba46b4..6da7dee02 100644 --- a/api/agent/lb_agent.go +++ b/api/agent/lb_agent.go @@ -102,6 +102,8 @@ type lbAgent struct { shutdown chan struct{} } +// NewLBAgent creates an Agent that knows how to load-balance function calls +// across a group of runner nodes. func NewLBAgent(da DataAccess, rp pool.RunnerPool, p pool.Placer) (Agent, error) { agent := createAgent(da, false) a := &lbAgent{ diff --git a/api/agent/protocol/doc.go b/api/agent/protocol/doc.go new file mode 100644 index 000000000..d73434763 --- /dev/null +++ b/api/agent/protocol/doc.go @@ -0,0 +1,12 @@ +// Package protocol defines the protocol between the Fn Agent and the code +// running inside of a container. When an Fn Agent wants to perform a function +// call it needs to pass that call to a container over stdin. The call is +// encoded in one of the following protocols. +// +// * Default I/O Format +// * JSON I/O Format +// * HTTP I/O Format +// +// For more information on the function formats see +// https://github.com/fnproject/fn/blob/master/docs/developers/function-format.md. +package protocol