github.com/xmidt-org/webpa-common@v1.11.9/device/listener.go (about)

     1  package device
     2  
     3  import (
     4  	"github.com/xmidt-org/wrp-go/v3"
     5  )
     6  
     7  // EventType is the type of device-related event
     8  type EventType uint8
     9  
    10  const (
    11  	// Connect indicates a successful device connection.  After receipt of this event, the given
    12  	// Device is able to receive requests.
    13  	Connect EventType = iota
    14  
    15  	// Disconnect indicates a device disconnection.  After receipt of this event, the given
    16  	// Device can no longer receive requests.
    17  	Disconnect
    18  
    19  	// MessageSent indicates that a message was successfully dispatched to a device.
    20  	MessageSent
    21  
    22  	// MessageReceived indicates that a message has been successfully received and
    23  	// dispatched to any goroutine waiting on it, as would be the case for a response.
    24  	MessageReceived
    25  
    26  	// MessageFailed indicates that a message could not be sent to a device, either because
    27  	// of a communications error or due to the device disconnecting.  For each enqueued message
    28  	// at the time of a device's disconnection, there will be (1) MessageFailed event.
    29  	MessageFailed
    30  
    31  	// TransactionComplete indicates that a response to a transaction has been received, and the
    32  	// transaction completed successfully (at least as far as the routing infrastructure can tell).
    33  	TransactionComplete
    34  
    35  	// TransactionBroken indicates receipt of a message that had a transaction key for which there
    36  	// was no waiting transaction
    37  	TransactionBroken
    38  
    39  	InvalidEventString string = "!!INVALID DEVICE EVENT TYPE!!"
    40  )
    41  
    42  var (
    43  	// blankEvent is an Event in its initial state.  Useful for quick state reset.
    44  	blankEvent Event
    45  )
    46  
    47  func (et EventType) String() string {
    48  	switch et {
    49  	case Connect:
    50  		return "Connect"
    51  	case Disconnect:
    52  		return "Disconnect"
    53  	case MessageSent:
    54  		return "MessageSent"
    55  	case MessageReceived:
    56  		return "MessageReceived"
    57  	case MessageFailed:
    58  		return "MessageFailed"
    59  	case TransactionComplete:
    60  		return "TransactionComplete"
    61  	case TransactionBroken:
    62  		return "TransactionBroken"
    63  	default:
    64  		return InvalidEventString
    65  	}
    66  }
    67  
    68  // Event represents a single occurrence of interest for device-related applications.
    69  // Instances of Event should be considered immutable by application code.  Also, Event
    70  // instances should not be stored across calls to a listener, as the infrastructure is
    71  // free to reuse Event instances.
    72  type Event struct {
    73  	// Type describes the kind of this event.  This field is always set.
    74  	Type EventType
    75  
    76  	// Device refers to the device, possibly disconnected, for which this event is being set.
    77  	// This field is always set.
    78  	Device Interface
    79  
    80  	// Message is the WRP message relevant to this event.
    81  	//
    82  	// Never assume that it is safe to use this Message outside the listener invocation.  Make
    83  	// a copy if this Message is needed by other goroutines or if it needs to be part of a long-lived
    84  	// data structure.
    85  	Message wrp.Typed
    86  
    87  	// Format is the encoding format of the Contents field
    88  	Format wrp.Format
    89  
    90  	// Contents is the encoded representation of the Message field.  It is always set if and only if
    91  	// the Message field is set.
    92  	//
    93  	// Never assume that it is safe to use this byte slice outside the listener invocation.  Make
    94  	// a copy if this byte slice is needed by other goroutines or if it needs to be part of a long-lived
    95  	// data structure.
    96  	Contents []byte
    97  
    98  	// Error is the error which occurred during an attempt to send a message.  This field is only populated
    99  	// for MessageFailed events when there was an actual error.  For MessageFailed events that indicate a
   100  	// device was disconnected with enqueued messages, this field will be nil.
   101  	Error error
   102  }
   103  
   104  // Listener is an event sink.  Listeners should never modify events and should never
   105  // store events for later use.  If data from an event is needed for another goroutine
   106  // or for long-term storage, a copy should be made.
   107  type Listener func(*Event)