getlantern / getlantern/unbounded

Document conventions for workers

Open
#22 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
57
Forks
1
Avg merge
20h 26m
Merged PRs (30d)
13

Description

The workerFSM abstraction is the way we implement protocol logic, and so it's likely we'll be writing and/or modifying workers to accommodate new discovery methods, transports, etc.

Implementers need to know a few things about writing workers, and this should be documented wherever makes the most sense:

Each workerFSM runs on its own goroutine. When you start a workerFSM, the worker's goroutine is created, and the worker begins executing. When you stop a workerFSM, it terminates that worker's goroutine at the conclusion of its currently executing state.

If you put a worker into an infinite loop, you must listen for its context cancellation -- otherwise, your worker will be unable to return from its current state, your worker will not obey calls to stop, and you will leak goroutines. The worker context is passed as the first argument to each FSMstate.

Similarly, if your worker creates child goroutines, it's your responsibility to figure out how to pass the worker context forward and terminate those goroutines when the worker context is cancelled.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names the workerFSM and FSMstate entry points but no file or test. Find the workerFSM implementation or existing documentation, then read the start/stop lifecycle and context handling. Done means implementers can find and follow the goroutine, cancellation, and child-goroutine conventions.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.