8000 Add descriptive comments to all public functions (#254) · open-lambda/open-lambda@2453666 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2453666

Browse files
hootanhthootanht
authored
Add descriptive comments to all public functions (#254)
Fixes #234 Add documentation comments to all public functions in the codebase. * Enable the `package-comments` rule in `golint.toml`. * Add documentation comments to all public functions in `src/bench/bench.go`. * Add documentation comments to all public functions in `src/boss/boss.go`. * Add documentation comments to all public functions in `src/main.go`. * Add documentation comments to all public functions in `src/worker/commands.go`. * Add documentation comments to all public functions in `src/worker/event/lambdaServer.go`. * Add documentation comments to all public functions in `src/worker/event/sockServer.go`. * Add documentation comments to all public functions in `src/worker/lambda/lambdaFunction.go`. * Add documentation comments to all public functions in `src/worker/lambda/lambdaInstance.go`. * Add documentation comments to all public functions in `src/worker/lambda/lambdaManager.go`. * Add documentation comments to all public functions in `src/worker/lambda/packages/depTracer.go`. * Add documentation comments to all public functions in `src/worker/lambda/packages/packagePuller.go`. * Add documentation comments to all public functions in `src/worker/lambda/zygote/importCache.go`. * Add documentation comments to all public functions in `src/worker/lambda/zygote/multiTree.go`. * Add documentation comments to all public functions in `src/worker/lambda/zygote/zygote.go`. * Add documentation comments to all public functions in `src/worker/sandbox/cgroups/cgroup.go`. * Add documentation comments to all public functions in `src/worker/sandbox/cgroups/pool.go`.
1 parent 46875a1 commit 2453666

File tree

17 files changed

+72
-29
lines changed

17 files changed

+72
-29
lines changed

‎golint.toml

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,6 @@ enableAllRules = true
22
errorCode = 2
33
#warningCode = 1
44

5-
#TODO we should eventually comment all public methods
6-
[rule.package-comments]
7-
Disabled = true
8-
95
#TODO get rid of all (or most) magic numbers
106
[rule.add-constant]
117
Disabled = true

‎src/bench/bench.go

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ type Call struct {
2020
name string
2121
}
2222

23+
// task is a function that processes requests from the reqQ channel and sends errors to the errQ channel.
2324
func task(reqQ chan Call, errQ chan error) {
2425
for {
2526
call, ok := <-reqQ
@@ -52,6 +53,7 @@ func task(reqQ chan Call, errQ chan error) {
5253
}
5354
}
5455

56+
// play_trace_cmd is a CLI command that plays a trace and prints the result.
5557
func play_trace_cmd(ctx *cli.Context) (error) {
5658
result, err := play_trace(ctx)
5759

@@ -63,6 +65,7 @@ func play_trace_cmd(ctx *cli.Context) (error) {
6365
return nil
6466
}
6567

68+
// play_trace plays a trace of lambda function calls and returns the result as a string.
6669
func play_trace(ctx *cli.Context) (string, error) {
6770
tracePath := ctx.String("trace")
6871
if tracePath == "" {
@@ -172,6 +175,7 @@ func play_trace(ctx *cli.Context) (string, error) {
172175
return result, nil
173176
}
174177

178+
// run_benchmark runs a benchmark with the specified parameters and returns the result as a string.
175179
func run_benchmark(ctx *cli.Context, name string, tasks int, functions int, func_template string) (string, error) {
176180
num_tasks := ctx.Int("tasks")
177181
if num_tasks != 0 {
@@ -261,6 +265,7 @@ func run_benchmark(ctx *cli.Context, name string, tasks int, functions int, func
261265
return result, nil
262266
}
263267

268+
// create_lambdas creates lambda functions for benchmarking.
264269
func create_lambdas(ctx *cli.Context) error {
265270
olPath, err := common.GetOlPath(ctx)
266271
if err != nil {
@@ -309,6 +314,7 @@ def f(event):
309314
return nil
310315
}
311316

317+
// make_action creates a CLI action function for running a benchmark.
312318
func make_action(name string, tasks int, functions int, func_template string) func(ctx *cli.Context) error {
313319
return func(ctx *cli.Context) error {
314320
result, err := run_benchmark(ctx, name, tasks, functions, func_template)
@@ -328,6 +334,7 @@ func make_action(name string, tasks int, functions int, func_template string) fu
328334
}
329335
}
330336

337+
// BenchCommands returns a list of CLI commands for benchmarking.
331338
func BenchCommands() []*cli.Command {
332339
cmds := []*cli.Command{
333340
{

‎src/boss/boss.go

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ type Boss struct {
2626
autoScaler autoscaling.Scaling
2727
}
2828

29+
// BossStatus handles the request to get the status of the boss.
2930
func (boss *Boss) BossStatus(w http.ResponseWriter, req *http.Request) {
3031
log.Printf("Receive request to %s\n", req.URL.Path)
3132

@@ -45,13 +46,15 @@ func (boss *Boss) BossStatus(w http.ResponseWriter, req *http.Request) {
4546
w.Write(b)
4647
}
4748

49+
// Close handles the request to close the boss.
4850
func (b *Boss) Close(_ http.ResponseWriter, _ *http.Request) {
4951
b.workerPool.Close()
5052
if Conf.Scaling == "threshold-scaler" {
5153
b.autoScaler.Close()
5254
}
5355
}
5456

57+
// ScalingWorker handles the request to scale the number of workers.
5558
func (b *Boss) ScalingWorker(w http.ResponseWriter, r *http.Request) {
5659
// STEP 1: get int (worker count) from POST body, or return an error
5760
if r.Method != "POST" {
@@ -96,6 +99,7 @@ func (b *Boss) ScalingWorker(w http.ResponseWriter, r *http.Request) {
9699
b.BossStatus(w, r)
97100
}
98101

102+
// BossMain is the main function for the boss.
99103
func BossMain() (err error) {
100104
fmt.Printf("WARNING! Boss incomplete (only use this as part of development process).\n")
101105

‎src/main.go

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ func overrideOpts(confPath, overridePath, optsStr string) error {
129129
return ioutil.WriteFile(overridePath, s, 0644)
130130
}
131131

132-
// corresponds to the "pprof mem" command of the admin tool.
132+
// pprofMem corresponds to the "pprof mem" command of the admin tool.
133133
func pprofMem(ctx *cli.Context) error {
134134
olPath, err := common.GetOlPath(ctx)
135135
if err != nil {
@@ -167,6 +167,7 @@ func pprofMem(ctx *cli.Context) error {
167167
return nil
168168
}
169169

170+
// pprofCpuStart corresponds to the "pprof cpu-start" command of the admin tool.
170171
func pprofCpuStart(ctx *cli.Context) error {
171172
olPath, err := common.GetOlPath(ctx)
172173
if err != nil {
@@ -202,6 +203,7 @@ func pprofCpuStart(ctx *cli.Context) error {
202203
return fmt.Errorf("Failed to start cpu profiling: %s\n", body)
203204
}
204205

206+
// pprofCpuStop corresponds to the "pprof cpu-stop" command of the admin tool.
205207
func pprofCpuStop(ctx *cli.Context) error {
206208
olPath, err := common.GetOlPath(ctx)
207209
if err != nil {

‎src/worker/commands.go

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -182,7 +182,7 @@ func upCmd(ctx *cli.Context) error {
182182
return fmt.Errorf("this code should not be F987 reachable")
183183
}
184184

185-
// status corresponds to the "status" command of the admin tool.
185+
// statusCmd corresponds to the "status" command of the admin tool.
186186
func statusCmd(ctx *cli.Context) error {
187187
olPath, err := common.GetOlPath(ctx)
188188
if err != nil {
@@ -210,7 +210,7 @@ func statusCmd(ctx *cli.Context) error {
210210
return nil
211211
}
212212

213-
// down corresponds to the "down" command of the admin tool.
213+
// downCmd corresponds to the "down" command of the admin tool.
214214
func downCmd(ctx *cli.Context) error {
215215
olPath, err := common.GetOlPath(ctx)
216216
if err != nil {
@@ -223,7 +223,7 @@ func downCmd(ctx *cli.Context) error {
223223
return bringToStoppedClean(olPath)
224224
}
225225

226-
// cleanup corresponds to the "force-cleanup" command of the admin tool.
226+
// cleanupCmd corresponds to the "force-cleanup" command of the admin tool.
227227
func cleanupCmd(ctx *cli.Context) error {
228228
olPath, err := common.GetOlPath(ctx)
229229
if err != nil {
@@ -232,6 +232,7 @@ func cleanupCmd(ctx *cli.Context) error {
232232
return bringToStoppedClean(olPath)
233233
}
234234

235+
// WorkerCommands returns a list of CLI commands for the worker.
235236
func WorkerCommands() []*cli.Command {
236237
pathFlag := cli.StringFlag{
237238
Name: "path",

‎src/worker/event/lambdaServer.go

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ type LambdaServer struct {
1616
lambdaMgr *lambda.LambdaMgr
1717
}
1818

19-
// getURLComponents parses request URL into its "/" delimated components
19+
// getURLComponents parses request URL into its "/" delimited components
2020
func getURLComponents(r *http.Request) []string {
2121
path := r.URL.Path
2222

@@ -67,15 +67,17 @@ func (s *LambdaServer) RunLambda(w http.ResponseWriter, r *http.Request) {
6767
}
6868
}
6969

70+
// Debug returns the debug information of the lambda manager.
7071
func (s *LambdaServer) Debug(w http.ResponseWriter, _ *http.Request) {
7172
w.Write([]byte(s.lambdaMgr.Debug()))
7273
}
7374

75+
// cleanup cleans up the lambda manager.
7476
func (s *LambdaServer) cleanup() {
7577
s.lambdaMgr.Cleanup()
7678
}
7779

78-
// NewLambdaServer creates a server based on the passed config."
80+
// NewLambdaServer creates a server based on the passed config.
7981
func NewLambdaServer() (*LambdaServer, error) {
8082
log.Printf("Starting new lambda server")
8183

‎src/worker/event/sockServer.go

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ type SOCKServer struct {
2727
sandboxes sync.Map
2828
}
2929

30+
// GetSandbox retrieves a sandbox by its ID.
3031
func (server *SOCKServer) GetSandbox(id string) sandbox.Sandbox {
3132
val, ok := server.sandboxes.Load(id)
3233
if !ok {
@@ -35,6 +36,7 @@ func (server *SOCKServer) GetSandbox(id string) sandbox.Sandbox {
3536
return val.(sandbox.Sandbox)
3637
}
3738

39+
// Create creates a new sandbox.
3840
func (server *SOCKServer) Create(w http.ResponseWriter, _ []string, args map[string]any) error {
3941
var leaf bool
4042
if b, ok := args["leaf"]; !ok || b.(bool) {
@@ -100,6 +102,7 @@ func (server *SOCKServer) Create(w http.ResponseWriter, _ []string, args map[str
100102
return nil
101103
}
102104

105+
// Destroy destroys a sandbox by its ID.
103106
func (server *SOCKServer) Destroy(_ http.ResponseWriter, rsrc []string, _ map[string]any) error {
104107
c := server.GetSandbox(rsrc[0])
105108
if c == nil {
@@ -111,6 +114,7 @@ func (server *SOCKServer) Destroy(_ http.ResponseWriter, rsrc []string, _ map[st
111114
return nil
112115
}
113116

117+
// Pause pauses a sandbox by its ID.
114118
func (server *SOCKServer) Pause(_ http.ResponseWriter, rsrc []string, _ map[string]any) error {
115119
c := server.GetSandbox(rsrc[0])
116120
if c == nil {
@@ -120,6 +124,7 @@ func (server *SOCKServer) Pause(_ http.ResponseWriter, rsrc []string, _ map[stri
120124
return c.Pause()
121125
}
122126

127+
// Unpause unpauses a sandbox by its ID.
123128
func (server *SOCKServer) Unpause(_ http.ResponseWriter, rsrc []string, _ map[string]any) error {
124129
c := server.GetSandbox(rsrc[0])
125130
if c == nil {
@@ -129,13 +134,15 @@ func (server *SOCKServer) Unpause(_ http.ResponseWriter, rsrc []string, _ map[st
129134
return c.Unpause()
130135
}
131136

137+
// Debug returns the debug information of the sandbox pool.
132138
func (server *SOCKServer) Debug(w http.ResponseWriter, _ []string, _ map[string]any) error {
133139
str := server.sbPool.DebugString()
134140
fmt.Printf("%s\n", str)
135141
w.Write([]byte(str))
136142
return nil
137143
}
138144

145+
// HandleInternal handles internal requests to the SOCK server.
139146
func (server *SOCKServer) HandleInternal(w http.ResponseWriter, r *http.Request) error {
140147
log.Printf("%s %s", r.Method, r.URL.Path)
141148

@@ -181,6 +188,7 @@ func (server *SOCKServer) HandleInternal(w http.ResponseWriter, r *http.Request)
181188
return fmt.Errorf("unknown op %s", rsrc[1])
182189
}
183190

191+
// Handle handles requests to the SOCK server.
184192
func (server *SOCKServer) Handle(w http.ResponseWriter, r *http.Request) {
185193
if err := server.HandleInternal(w, r); err != nil {
186194
log.Printf("Request Handler Failed: %v", err)
@@ -189,6 +197,7 @@ func (server *SOCKServer) Handle(w http.ResponseWriter, r *http.Request) {
189197
}
190198
}
191199

200+
// cleanup cleans up the SOCK server.
192201
func (server *SOCKServer) cleanup() {
193202
server.sandboxes.Range(func(key, val any) bool {
194203
val.(sandbox.Sandbox).Destroy("SOCKServer cleanup")
@@ -197,7 +206,7 @@ func (server *SOCKServer) cleanup() {
197206
server.sbPool.Cleanup()
198207
}
199208

200-
// NewSOCKServer creates a server based on the passed config."
209+
// NewSOCKServer creates a server based on the passed config.
201210
func NewSOCKServer() (*SOCKServer, error) {
202211
log.Printf("Start SOCK Server")
203212

‎src/worker/lambda/lambdaFunction.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ type LambdaFunc struct {
4040
killChan chan chan bool
4141
}
4242

43+
// Invoke handles the invocation of the lambda function.
4344
func (f *LambdaFunc) Invoke(w http.ResponseWriter, r *http.Request) {
4445
t := common.T0("LambdaFunc.Invoke")
4546
defer t.T1()
@@ -359,6 +360,7 @@ func (f *LambdaFunc) Task() {
359360
}
360361
}
361362

363+
// newInstance creates a new lambda instance.
362364
func (f *LambdaFunc) newInstance() {
363365
if f.codeDir == "" {
364366
panic("cannot start instance until code has been fetched")
@@ -376,6 +378,7 @@ func (f *LambdaFunc) newInstance() {
376378
go linst.Task()
377379
}
378380

381+
// Kill signals the lambda function to terminate all instances and perform cleanup.
379382
func (f *LambdaFunc) Kill() {
380383
done := make(chan bool)
381384
f.killChan <- done

‎src/worker/lambda/lambdaInstance.go

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -222,6 +222,7 @@ func (linst *LambdaInstance) Task() {
222222
}
223223
}
224224

225+
// TrySendError attempts to send an error response to the client.
225226
func (linst *LambdaInstance) TrySendError(req *Invocation, statusCode int, msg string, sb sandbox.Sandbox) {
226227
if statusCode > 0 {
227228
req.w.WriteHeader(statusCode)

‎src/worker/lambda/lambdaManager.go

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ type Invocation struct {
4646
execMs int
4747
}
4848

49+
// NewLambdaMgr creates a new LambdaMgr instance and initializes its subsystems.
4950
func NewLambdaMgr() (res *LambdaMgr, err error) {
5051
mgr := &LambdaMgr{
5152
lfuncMap: make(map[string]*LambdaFunc),
@@ -101,7 +102,7 @@ func NewLambdaMgr() (res *LambdaMgr, err error) {
101102
return mgr, nil
102103
}
103104

104-
// Returns an existing instance (if there is one), or creates a new one
105+
// Get returns an existing LambdaFunc instance or creates a new one if it doesn't exist.
105106
func (mgr *LambdaMgr) Get(name string) (f *LambdaFunc) {
106107
mgr.mapMutex.Lock()
107108
defer mgr.mapMutex.Unlock()
@@ -127,10 +128,12 @@ func (mgr *LambdaMgr) Get(name string) (f *LambdaFunc) {
127128
return f
128129
}
129130

131+
// Debug returns the debug information of the sandbox pool.
130132
func (mgr *LambdaMgr) Debug() string {
131133
return mgr.sbPool.DebugString() + "\n"
132134
}
133135

136+
// DumpStatsToLog logs the profiling information of the LambdaMgr.
134137
func (_ *LambdaMgr) DumpStatsToLog() {
135138
snapshot := common.SnapshotStats()
136139

@@ -168,6 +171,7 @@ func (_ *LambdaMgr) DumpStatsToLog() {
168171
time(2, "LambdaInstance-RoundTrip", "LambdaInstance-ServeRequests")
169172
}
170173

174+
// Cleanup performs cleanup operations for the LambdaMgr and its subsystems.
171175
func (mgr *LambdaMgr) Cleanup() {
172176
mgr.mapMutex.Lock() // don't unlock, because this shouldn't be used anymore
173177

0 commit comments

Comments
 (0)
0