dennis-tra/pcp

package service

import (
    "context"
    "sync"

    "github.com/pkg/errors"

    "github.com/dennis-tra/pcp/internal/log"
)

// State represents the lifecycle states of a service.
type State uint8

const (
    // These are the concrete lifecycle manifestations.
    Idle State = iota
    Started
    Stopping
    Stopped
)

// ErrServiceAlreadyStarted is returned if there are multiple calls to ServiceStarted.
// If this happens somethings wrong :/
var ErrServiceAlreadyStarted = errors.New("the service was already started in the past")

// Service represents an entity that runs in a
// separate go routine and where its lifecycle
// needs to be handled externally.
type Service struct {
    // The name of the service for logging purposes
    name string

    // A context that can be used for long running
    // io operations of the service. This context
    // gets cancelled when the service receives a
    // shutdown signal. It's controversial to store
    // a context in a struct field but I believe
    // that it makes sense here.
    ctx    context.Context
    cancel context.CancelFunc

    // The current state of this service.
    lk    sync.RWMutex
    state State

    // When a message is sent to this channel it
    // starts to gracefully shut down.
    shutdown chan struct{}

    // When a message is sent to this channel
    // the service has shut down.
    done chan struct{}
}

// New instantiates an initialised Service struct. It
// deliberately does not accept a context as an input
// parameter as I consider long running service life-
// cycle handling with contexts as a bad practice.
// Contexts belong in request/response paths and
// Services should be handled via channels.
func New(name string) *Service {
    ctx, cancel := context.WithCancel(context.Background())
    return &Service{
        ctx:      ctx,
        name:     name,
        cancel:   cancel,
        state:    Idle,
        shutdown: make(chan struct{}),
        done:     make(chan struct{}),
    }
}

// ServiceStarted marks this service as started.
func (s *Service) ServiceStarted() error {
    log.Debugln(s.name, "- Service has started")

    s.lk.Lock()
    defer s.lk.Unlock()

    if s.state != Idle {
        return ErrServiceAlreadyStarted
    }
    s.state = Started

    go func() {
        select {
        case <-s.shutdown:
        case <-s.done:
        }
        s.cancel()
    }()

    return nil
}

// SigShutdown exposes the shutdown channel to listen for
// shutdown instructions.
func (s *Service) SigShutdown() chan struct{} {
    return s.shutdown
}

// SigDone exposes the done channel to listen for
// service termination.
func (s *Service) SigDone() chan struct{} {
    return s.done
}

// ServiceStopped marks this service as stopped and
// ultimately releases an external call to Shutdown.
func (s *Service) ServiceStopped() {
    s.lk.Lock()
    defer s.lk.Unlock()

    if s.state == Idle || s.state == Stopped {
        return
    }
    s.state = Stopped

    close(s.done)
    log.Debugln(s.name, "- Service has stopped")
}

// ServiceContext returns the context associated with this
// service. This context is passed into requests or similar
// that are initiated from this service. Doing it this way
// we can cancel this contexts when someone shuts down
// the service, which results in all requests being stopped.
func (s *Service) ServiceContext() context.Context {
    return s.ctx
}

// Shutdown instructs the service to gracefully shut down.
// This function blocks until the done channel was closed
// which happens when ServiceStopped is called.
func (s *Service) Shutdown() {
    log.Debugln(s.name, "- Service shutting down...")

    s.lk.Lock()
    if s.state != Started {
        s.lk.Unlock()
        return
    }
    s.state = Stopping
    s.lk.Unlock()

    close(s.shutdown)
    <-s.done
    log.Debugln(s.name, "- Service was shut down")
}