1package event 2 3import ( 4 "io" 5 "reflect" 6) 7 8// SubscriptionOpt represents a subscriber option. Use the options exposed by the implementation of choice. 9type SubscriptionOpt = func(interface{}) error 10 11// EmitterOpt represents an emitter option. Use the options exposed by the implementation of choice. 12type EmitterOpt = func(interface{}) error 13 14// CancelFunc closes a subscriber. 15type CancelFunc = func() 16 17// wildcardSubscriptionType is a virtual type to represent wildcard 18// subscriptions. 19type wildcardSubscriptionType interface{} 20 21// WildcardSubscription is the type to subscribe to to receive all events 22// emitted in the eventbus. 23var WildcardSubscription = new(wildcardSubscriptionType) 24 25// Emitter represents an actor that emits events onto the eventbus. 26type Emitter interface { 27 io.Closer 28 29 // Emit emits an event onto the eventbus. If any channel subscribed to the topic is blocked, 30 // calls to Emit will block. 31 // 32 // Calling this function with wrong event type will cause a panic. 33 Emit(evt interface{}) error 34} 35 36// Subscription represents a subscription to one or multiple event types. 37type Subscription interface { 38 io.Closer 39 40 // Out returns the channel from which to consume events. 41 Out() <-chan interface{} 42} 43 44// Bus is an interface for a type-based event delivery system. 45type Bus interface { 46 // Subscribe creates a new Subscription. 47 // 48 // eventType can be either a pointer to a single event type, or a slice of pointers to 49 // subscribe to multiple event types at once, under a single subscription (and channel). 50 // 51 // Failing to drain the channel may cause publishers to block. 52 // 53 // If you want to subscribe to ALL events emitted in the bus, use 54 // `WildcardSubscription` as the `eventType`: 55 // 56 // eventbus.Subscribe(WildcardSubscription) 57 // 58 // Simple example 59 // 60 // sub, err := eventbus.Subscribe(new(EventType)) 61 // defer sub.Close() 62 // for e := range sub.Out() { 63 // event := e.(EventType) // guaranteed safe 64 // [...] 65 // } 66 // 67 // Multi-type example 68 // 69 // sub, err := eventbus.Subscribe([]interface{}{new(EventA), new(EventB)}) 70 // defer sub.Close() 71 // for e := range sub.Out() { 72 // select e.(type): 73 // case EventA: 74 // [...] 75 // case EventB: 76 // [...] 77 // } 78 // } 79 Subscribe(eventType interface{}, opts ...SubscriptionOpt) (Subscription, error) 80 81 // Emitter creates a new event emitter. 82 // 83 // eventType accepts typed nil pointers, and uses the type information for wiring purposes. 84 // 85 // Example: 86 // em, err := eventbus.Emitter(new(EventT)) 87 // defer em.Close() // MUST call this after being done with the emitter 88 // em.Emit(EventT{}) 89 Emitter(eventType interface{}, opts ...EmitterOpt) (Emitter, error) 90 91 // GetAllEventTypes returns all the event types that this bus knows about 92 // (having emitters and subscribers). It omits the WildcardSubscription. 93 // 94 // The caller is guaranteed that this function will only return value types; 95 // no pointer types will be returned. 96 GetAllEventTypes() []reflect.Type 97} 98