README
¶
Banji
Banji is a concurrent event engine and EDA framework for Go.
[!CAUTION] Banji is in the very, very early stages of development.
There is undoubtedly room for improvement, and this codebase is bound to change. Please keep this in mind if you intend to use this package.
About
I created Banji mainly for myself. The goal of Banji is to provide a structured and extensible event engine that can be used for anything. There are some events we do not need to handle or care about; some capabilities we simply do not need. Conversely, there are some components we may desire in the future but cannot reasonably foresee needing now. Therefore, we shouldn't need to implement an interface and change our implementation every time some new component or capability comes along.
Features
- Concurrent demultiplexing
- Event priorities
- Built-in events for happenings within the engine
- Proactor-esque design (see
ErrorEvent) - Reflection-free routing
- Graceful shutdown mechanics
- Tick-based engine loop
- Unified logging system
Quick Start
Check the wiki for a quick tutorial on how to create events, receivers, and components.
func main() {
// This allows us to check for the program exiting.
stop := make(chan os.Signal)
signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
eng := banji.New(
banji.WithTPS(128),
banji.WithDemuxers(8),
)
// Register your receivers here.
eng.Subscribe(NewMyReceiver("Hiii!"))
eng.Start() // This is non-blocking.
defer eng.Stop()
// Once the engine is running, you and other components
// can then post events to the engine.
eng.Post(NewMyEvent("Hello!"), 255)
<- stop
}
Documentation
¶
Overview ¶
Package banji provides a concurrent proactor and a framework for implementing EDA.
Index ¶
- Constants
- type Bus
- type Component
- type Engine
- type ErrorEvent
- type Event
- type EventEmbed
- type Level
- type Log
- func (l *Log) Add(k string, v any) *Log
- func (l *Log) Data() LogData
- func (l *Log) Description() string
- func (l *Log) ID() uuid.UUID
- func (l *Log) Kind() string
- func (l *Log) Level() Level
- func (l *Log) MarshalJSON() ([]byte, error)
- func (l *Log) Postmark() time.Time
- func (l *Log) Value(key string) any
- func (l *Log) With(x ...any) error
- type LogData
- type LogEvent
- type LogField
- type Option
- type Options
- type PostTickEvent
- type PreTickEvent
- type Receiver
- type ReceiverEmbed
- type StartEvent
- type StopEvent
Constants ¶
const ErrorTopic = "banji.error"
const LogTopic = "banji.log"
const PostTickTopic = "banji.postTick"
const PreTickTopic = "banji.preTick"
const StartTopic = "banji.start"
const StopTopic = "banji.stopLoop"
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bus ¶
type Bus interface {
Tick()
Subscribe(r Receiver)
Unsubscribe(r Receiver)
Post(event Event, priority uint8)
Size() int
}
A Bus is an entity that can receive and route Event types to Receiver types.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
The Engine brokers communication between decoupled components via Event and Receiver.
func (*Engine) Post ¶
Post posts an Event to the engine, which will be handled on the next available tick.
func (*Engine) Start ¶
func (eng *Engine) Start()
Start is a non-blocking operation that starts the engine. Components can listen for StartTopic to be notified when this function has been executed.
func (*Engine) Stop ¶
func (eng *Engine) Stop()
Stop is a blocking operation that gracefully shuts down the engine. Components can listen for StopTopic to be notified when this function has been executed.
func (*Engine) Subscribe ¶
Subscribe registers a Receiver to its associated topic. A Receiver can only be subscribed once. Subsequent calls to Subscribe with the same Receiver will have no effect.
func (*Engine) Unsubscribe ¶
Unsubscribe unregisters a Receiver. Note that this can be an expensive operation to perform; thus, it should be used sparingly.
type ErrorEvent ¶
type ErrorEvent struct {
EventEmbed
// contains filtered or unexported fields
}
ErrorEvent is an Event posted when a Receiver's handler method returns an error.
func (*ErrorEvent) Error ¶
func (e *ErrorEvent) Error() error
func (*ErrorEvent) Topic ¶
func (e *ErrorEvent) Topic() string
type Event ¶
type Event interface {
ID() uuid.UUID
Postmark() time.Time
Topic() string
Cancel()
Canceled() bool
// contains filtered or unexported methods
}
An Event is any type that can be emitted and routed by the engine.
type EventEmbed ¶
type EventEmbed struct {
// contains filtered or unexported fields
}
EventEmbed contains internal methods required to implement the Event interface.
func (*EventEmbed) Cancel ¶
func (e *EventEmbed) Cancel()
func (*EventEmbed) Canceled ¶
func (e *EventEmbed) Canceled() bool
func (*EventEmbed) ID ¶
func (e *EventEmbed) ID() uuid.UUID
func (*EventEmbed) Postmark ¶
func (e *EventEmbed) Postmark() time.Time
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
func (*Log) Description ¶
func (*Log) MarshalJSON ¶
type LogEvent ¶
type LogEvent struct {
EventEmbed
// contains filtered or unexported fields
}
LogEvent is an Event posted when a log message is created.
func NewLogEvent ¶
type Options ¶
func NewOptions ¶
type PostTickEvent ¶
type PostTickEvent struct {
EventEmbed
// contains filtered or unexported fields
}
PostTickEvent is an Event posted once the work for a given tick has concluded. Therefore, it does not necessarily mean that a new tick has also begun (you should listen for PreTickEvent instead for such purposes).
func (*PostTickEvent) Tick ¶
func (e *PostTickEvent) Tick() time.Time
func (*PostTickEvent) Topic ¶
func (e *PostTickEvent) Topic() string
type PreTickEvent ¶
type PreTickEvent struct {
EventEmbed
// contains filtered or unexported fields
}
PreTickEvent is an Event posted when a new tick has begun.
func (*PreTickEvent) Tick ¶
func (e *PreTickEvent) Tick() time.Time
func (*PreTickEvent) Topic ¶
func (e *PreTickEvent) Topic() string
type Receiver ¶
type Receiver interface {
ID() uuid.UUID
Postmark() time.Time
Topic() string
Handle(event Event) error
// contains filtered or unexported methods
}
A Receiver is any type that can receive and handle Event types.
type ReceiverEmbed ¶
type ReceiverEmbed struct {
// contains filtered or unexported fields
}
ReceiverEmbed contains internal methods required to implement the Receiver interface.
func (*ReceiverEmbed) ID ¶
func (r *ReceiverEmbed) ID() uuid.UUID
func (*ReceiverEmbed) Postmark ¶
func (r *ReceiverEmbed) Postmark() time.Time
type StartEvent ¶
type StartEvent struct {
EventEmbed
}
StartEvent is an Event posted when the Engine starts. It primarily serves as a signal to components to perform any bootstrapping or initialization they may require.
func (*StartEvent) Topic ¶
func (e *StartEvent) Topic() string
type StopEvent ¶
type StopEvent struct {
EventEmbed
}
StopEvent is an Event posted when the engine is about to shut down. It primarily serves as a signal to components to perform any shutdown or cleanup mechanics they may require. StopEvent should not be used as a catalyst for posting additional events, as they will not be routed by the engine once StopEvent has been posted.
Source Files
Directories