Merge pull request #2746 from nishanttotla/events-restructuring

Adding some clarifying comments for event handling

Author: nishanttotla

api/primary.go

@@ -117,7 +117,16 @@ func profilerSetup(mainRouter *mux.Router, path string) {
 // NewPrimary creates a new API router.
 func NewPrimary(cluster cluster.Cluster, tlsConfig *tls.Config, status StatusHandler, debug, enableCors bool) *mux.Router {
 	// Register the API events handler in the cluster.
+
+	// NewEventsHandler creates a new eventsHandler object.
+	// The new eventsHandler is initialized with no writers or channels.
+	// This is in api/events.go
 	eventsHandler := newEventsHandler()
+	// This just calls c.eventHandlers.RegisterEventHandler(eventsHandler) internally.
+	// Eventually, eventsHandler is added to the Cluster struct's EventHandlers map, if it
+	// doesn't already exist there. The Cluster struct implements the cluster.EventHandler
+	// interface, as does eventsHandler. So calling the Handle function for a Cluster object
+	// will eventually call the Handle function for eventsHandler.
 	cluster.RegisterEventHandler(eventsHandler)
 
 	context := &context{

cluster/engine.go

@@ -228,6 +228,11 @@ func (e *Engine) StartMonitorEvents() {
 		close(ec)
 	}()
 
+	// this call starts a goroutine that collects events from the the engine, and returns an error to
+	// ec (the error channel) in case an error occurs. The corresponding Stop() function tears this
+	// down. The eventsMonitor itself is initialized using the apiClient and handler (defined below)
+	// The handler function processes events as received from the engine and decides what to do based
+	// on each event. Moreover, it also calls the eventHandler's Handle() function.
 	e.eventsMonitor.Start(ec)
 }
 

cluster/swarm/cluster.go

@@ -305,6 +305,13 @@ func (c *Cluster) addEngine(addr string) bool {
 	}
 
 	engine := cluster.NewEngine(addr, c.overcommitRatio, c.engineOpts)
+	// This passes c, which has a Handle(Event) (error) function defined, which acts as the handler
+	// for events. This is the cluster level handler that is called by individual engines when they
+	// receive/emit events. This Handler in turn calls the eventHandlers.Handle() function.
+	// eventHandlers is a map from EventHandler -> struct{}, and eventHandlers.Handle() simply calls
+	// the Handle function for each of the EventHander objects in the map. Remember that EventHandler
+	// is an interface, that is implemented by both the Cluster object, as well as the eventsHandler
+	// object in api/events.go
 	if err := engine.RegisterEventHandler(c); err != nil {
 		log.Error(err)
 	}