go-hep.org/x/hep@v0.38.1/fwk/fwk.go (about)

     1  // Copyright ©2017 The go-hep Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package fwk provides a set of tools to process High Energy Physics events data.
     6  // fwk is a components-based framework, a-la Gaudi, with builtin support for concurrency.
     7  //
     8  // A fwk application consists of a set of components (fwk.Task) which are:
     9  //   - (optionally) configured
    10  //   - started
    11  //   - given the chance to process each event
    12  //   - stopped
    13  //
    14  // Helper components (fwk.Svc) can provide additional features (such as a
    15  // whiteboard/event-store service, a data-flow service, ...) but do not
    16  // typically take (directly) part of the event processing.
    17  //
    18  // Typically, users will implement fwk.Tasks, ie:
    19  //
    20  //	type MyTask struct {
    21  //	  fwk.TaskBase
    22  //	}
    23  //
    24  //	// Configure is called once, after having read the properties
    25  //	// from the data-cards.
    26  //	func (tsk *MyTask) Configure(ctx fwk.Context) error { return nil }
    27  //
    28  //	// StartTask is called once (sequentially), just before
    29  //	// the main event-loop processing.
    30  //	func (tsk *MyTask) StartTask(ctx fwk.Context) error { return nil }
    31  //
    32  //	// Process is called for each event, (quite) possibly concurrently.
    33  //	func (tsk *MyTask) Process(ctx fwk.Context)   error { return nil }
    34  //
    35  //	// StopTask is called once (sequentially), just after the
    36  //	// main event-loop processing finished.
    37  //	func (tsk *MyTask) StopTask(ctx fwk.Context)  error { return nil }
    38  //
    39  // A fwk application processes data and leverages concurrency at
    40  // two different levels:
    41  //   - event-level concurrency: multiple events are processed concurrently
    42  //     at any given time, during the event loop;
    43  //   - task-level concurrency: during the event loop, multiple tasks are
    44  //     executing concurrently.
    45  //
    46  // To ensure the proper self-consistency of the global processed event,
    47  // components need to express their data dependencies (input(s)) as well
    48  // as the data they produce (output(s)) for downstream components.
    49  // This is achieved by the concept of a fwk.Port.
    50  // A fwk.Port consists of a pair { Name string; Type reflect.Type }
    51  // where 'Name' is the unique location in the event-store,
    52  // and 'Type' the expected 'go' type of the data at that event-store location.
    53  //
    54  // fwk.Ports can be either INPUT ports or OUTPUT ports.
    55  // Components declare INPUT ports and OUTPUT ports during the 'Configure' stage
    56  // of a fwk application, like so:
    57  //
    58  //	t := reflect.TypeOf([]Electron{})
    59  //	err = component.DeclInPort("Electrons", t)
    60  //	err = component.DeclOutPort("ReScaledElectrons", t)
    61  //
    62  // Then, during the event processing, one gets and puts data from/to the store
    63  // like so:
    64  //
    65  //	func (tsk *MyTask) Process(ctx fwk.Context) error {
    66  //	   var err error
    67  //
    68  //	   // retrieve the store associated with this event / region-of-interest
    69  //	   store := ctx.Store()
    70  //
    71  //	   v, err := store.Get("Electrons")
    72  //	   if err != nil {
    73  //	      return err
    74  //	   }
    75  //	   eles := v.([]Electron) // type-cast to the correct (underlying) type
    76  //
    77  //	   // create output collection
    78  //	   out := make([]Electron, 0, len(eles))
    79  //
    80  //	   // make sure the collection will be put in the store
    81  //	   defer func() {
    82  //	      err = store.Put("ReScaledElectrons", out)
    83  //	   }()
    84  //
    85  //	   // ... do some massaging with 'eles' and 'out'
    86  //
    87  //	   return err
    88  //	}
    89  package fwk // import "go-hep.org/x/hep/fwk"