mlsr/utils/Signal.go

/*
 * Copyright (c) 2014-2022,  Peking University Shenzhen Graduate School
 *
 * This file is part of MIN-Sync.
 * See AUTHORS.md for complete list of MIN-Sync authors and contributors.
 *
 * MIN-Sync is free software: you can redistribute it and/or modify it under the terms
 * of the GNU Lesser General Public License as published by the Free Software Foundation,
 * either version 3 of the License, or (at your option) any later version.
 *
 * MIN-Sync is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 * PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License along with
 * MIN-Sync, e.g., in COPYING.md file.  If not, see <http://www.gnu.org/licenses/>.
 *

 * This file incorporates work covered by the following copyright and
 * permission notice:

 * The MIT License (MIT)

 * Copyright (c) 2000 Arash Partow

 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:

 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.

 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

package utils

import (
	"minlib/common"
	"reflect"

	"github.com/liyue201/gostl/ds/vector"
)

type DisconnectFunction = func()

/** \brief represents a connection to a signal
 *  \note This type is copyable. Any copy can be used to disconnect.
 */
type Connection struct {
	disconnect DisconnectFunction
}

/** \brief disconnects from the signal
 *  \note If the connection is already disconnected, or if the Signal has been cleared,
 *        this operation has no effect.
 *  \warning During signal emission, attempting to disconnect a connection other than
 *           the executing handler's own connection results in undefined behavior.
 */
func (c *Connection) Disconnect() {
	if c.IsConnected() {
		c.disconnect()
	}
}

/** \brief check if connected to the signal
 */
func (c *Connection) IsConnected() bool {
	return c.disconnect != nil
}

/** \brief compare for equality
 *
 *  Two connections are equal if they both point to the same connection that isn't disconnected,
 *  or they are both disconnected.
 */
func (c *Connection) Equals(other *Connection) bool {
	return (!c.IsConnected() && !other.IsConnected()) || reflect.ValueOf(c.disconnect).Pointer() == reflect.ValueOf(other.disconnect).Pointer()
}

/* Factory Method for Connection */
func NewConnectionByDisconnectFunc(df DisconnectFunction) *Connection {
	c := new(Connection)
	c.disconnect = df
	return c
}

/** \brief represents a function that can connect to the signal
 */
type Handler = func(...interface{})

/** \brief provides a lightweight signal / event system
 *
 *  To declare a signal:
 *    factory method;
 *  To connect to a signal:
 *    owner.signalName.connect(f);
 *    Multiple functions can connect to the same signal.
 *  To emit a signal from owner:
 *    this->signalName.emit(arg1, arg2);
 *
 *  \sa signal-emit.hpp allows owner's derived classes to emit signals
 */

type Signal struct {
	slots SlotList
	/** \brief is a signal handler executing?
	 */
	isExecuting bool
	currentSlot SlotIterator
}

/** \brief connects a handler to the signal
 *  \note If invoked from a handler, the new handler won't receive the current emitted signal.
 *  \warning The handler is permitted to disconnect itself, but it must ensure its validity.
 */
func (s *Signal) Connect(handler Handler) *Connection {
	slot := NewSlotByHandler(handler)
	slotIterator := s.slots.Insert(s.slots.End(), slot)

	/* disconnect management */
	df := func() {
		s.disconnect(slotIterator)
	}
	slot.Disconnect = df                         /* strong reference */
	weakPtr := NewConnectionByDisconnectFunc(df) /* weak reference */
	slot.Connection = weakPtr                    /* slot takes over connection */
	return weakPtr
}

/** \brief connects a single-shot handler to the signal
 *
 *  After the handler is executed once, it is automatically disconnected.
 */
func (s *Signal) ConnectSingleShot(handler Handler) *Connection {
	slot := new(Slot)
	slotIterator := s.slots.Insert(s.slots.End(), slot)

	df := func() {
		s.disconnect(slotIterator)
	}
	conn := NewConnectionByDisconnectFunc(df)

	slot.Disconnect = df
	slot.Connection = conn
	slot.Handler = func(args ...interface{}) {
		handler(args)
		conn.Disconnect()
	}

	return conn
}

/** \retval true if there is no connection
 */
func (s *Signal) IsEmpty() bool {
	return !s.isExecuting && s.slots.Empty()
}

/** \brief emits a signal
 *  \param args arguments passed to all handlers
 *  \warning Emitting the signal from a handler is undefined behavior.
 *  \note If a handler throws, the exception will be propagated to the caller
 *        who emits this signal, and some handlers may not be executed.
 */
func (s *Signal) Emit(args ...interface{}) {
	if s.IsEmpty() {
		return
	}

	defer func() {
		s.isExecuting = false
	}()
	s.isExecuting = true

	it := s.slots.Begin()
	last := s.slots.Last()
	isLast := false
	for !isLast {
		isLast = it.Equal(last)
		s.currentSlot = it
		s.currentSlot.Value().(*Slot).Handler(args...)

		// disconnect while executing current slot
		if s.currentSlot.Equal(s.slots.End()) {
			it = s.slots.Erase(it)
		} else {
			it = it.Next().(SlotIterator)
		}
	}
}

/** \brief disconnects the handler in a slot
 */
func (s *Signal) disconnect(iterator SlotIterator) {
	if s.isExecuting {
		// during signal emission, only the currently executing handler can be disconnected
		if !s.currentSlot.Equal(iterator) {
			common.LogWarn("cannot disconnect another handler from a handler")
			return
		}

		// this serves to indicate that the current slot needs to be erased from the list
		// after it finishes executing; we cannot do it here because of bug #2333
		s.currentSlot = s.slots.End()
		// destruct
		iterator.Value().(*Slot).Destruct()
	} else {
		iterator.Value().(*Slot).Destruct()
		s.slots.Erase(iterator)
	}
}

/* Clear
 */
func (s *Signal) Clear() {
	/* \warn should only called when signal is not executing */
	s.currentSlot = nil

	/* clean all slots */
	it := s.slots.Begin()
	for !it.Equal(s.slots.End()) {
		it.Value().(*Slot).Destruct()
		it = it.Next().(*vector.VectorIterator)
	}

	/* clean slots container */
	s.slots.Clear()
	// s.slots = nil is not needed
}

/* factory method for Signal */
func NewSignal() *Signal {
	s := new(Signal)
	s.isExecuting = false
	s.slots = vector.New()
	return s
}

type SlotList = *vector.Vector

type SlotIterator = *vector.VectorIterator

type Slot struct {
	/** \brief weak reference of disconnect function
	connection's lifetime is taken over by slot
	*/
	*Connection
	/** \brief the handler function who will receive emitted signals
	 */
	Handler Handler
	/** \brief the disconnect function which will disconnect this handler
	 *
	 *  In practice this is the Signal.Disconnect method bound to a ptr
	 *  pointing at this slot.
	 *
	 *  Connection also has a ptr which references the same function object.
	 *  When the slot is erased or the signal is destructed, this function object is
	 *  destructed, and the related Connections cannot disconnect this slot again.
	 */
	Disconnect DisconnectFunction
}

/* Clear
\warn cannot use the slot which has been already Destructed
*/
func (s *Slot) Destruct() {
	s.Handler = nil
	s.Disconnect = nil
	s.Connection.disconnect = nil
	s.Connection = nil
}

func NewSlotByHandler(handler Handler) *Slot {
	s := new(Slot)
	s.Handler = handler
	return s
}