/gsignal

A lightweight Godot/Qt inspired signals and slots for Go

Primary LanguageGoMIT LicenseMIT

Godot-like signals library

Build Status PkgGoDev

Overview

A Godot-inspired signals library for Go.

Key features:

  • Amortized zero allocations in most use cases
  • Efficient Connect, Emit, Disconnect
  • Generic-based API gives us type safety and convenience

Some games that were built with this library (this list is incomplete):

Why bother and use something like this?

  • It reduces the objects coupling
  • It's an elegant event listener solution for Go
  • Signals are a familiar concept (Godot, Phaser, Qt, ...)

Installation

go get github.com/quasilyte/gsignal

Quick Start

package main

import (
	"fmt"

	"github.com/quasilyte/gsignal"
)

type button struct {
	Name         string
	EventClicked gsignal.Event[*button]
}

func (b *button) Click() { b.EventClicked.Emit(b) }

type listener struct {
	disposed bool
}

func (l *listener) IsDisposed() bool { return l.disposed }

func (l *listener) onClick(b *button) {
	fmt.Println("listener on click")
}

func main() {
	b := &button{Name: "example"}
	b.Click() // nothing happens, 0 connections

	i := 1
	b.EventClicked.Connect(nil, func(b *button) {
		fmt.Printf("%s clicked (%d)\n", b.Name, i)
		i++
	})
	b.Click() // prints "example clicked (1)" once
	b.Click() // prints "example clicked (2)" once; again

	l := &listener{}
	b.EventClicked.Connect(l, l.onClick)
	b.Click() // prints "example clicked (3)", then "listener on click"

	l.disposed = true // this will cause a disconnect
	b.Click()         // prints "example clicked (4)" once
}

Introduction

This concept is borrowed from Godot signals, but it also resembles Signals and Slots from Qt.

In gsignal terms:

  • Signal = a field inside a struct
  • Slot = a function (or method value) bound to a signal
  • Disconnect = remove bound function
  • Emit = call all bound functions

This library disconnects disposed objects automatically. This is convenient when you connect a scene object to some Event. When object goes away from a scene (becomes disposed), there is no need to call its event handler anymore.

Thread Safety Notice

This library never does any synchronization on its own. It's implied that event emitters and their subscribers are executed inside the same goroutine.

This is possible in the game context, but it may not be as easy to enforce in some other applications.

Let's imagine that you want to do a background task in a game and provide a signal-style event for its completion. You spawn a goroutine for the task, but you keep the code outside look like it's still single-threaded. All concurrent communication should be incapsulated in the object owning the Event object. When this object knows that this concurrent job is completed, it should emit the event and notify all the subscribers.