[sigc] Draft #1, Proposal for standardization in C++ Library TR2

[Carl Nygard <cjnygard verizon net>]

Sourceforge has been impossible for me to get through to, so in the
absence of being able to checkin to CVS, I include the draft doc with
some added text.  Mostly a summary of the existing practice, grabbed
from existing docs.  Also some issues noted, and a rough first attempt
at the Motivation.

I'm a better editor than writer, I think, so suggestions welcome.

Please notify me if Sourceforge stabilizes, in case it's a problem on my
end.

Regards,
Carl

Title: Signals & Slots for Library TR2

Signals & Slots for Library TR2

Document number: NXXXX=05-NNNN
Date: July 26, 2005
Project: Programming Language C++, Library Working Group
Authors: Murray Cumming <murrayc -at- murrayc.com>
   Douglas Gregor <doug.gregor -at- gmail.com>
   Carl Nygard <cjnygard -at-
verizon.net>
Reply-to: One of us

Table of contents

(Fill in when we know the structure)

Motivation

Multi-target callbacks in general, uses, etc. We should have a simple
example, maybe with some kind of diagram that shows the signal/slot
connections in a small GUI application.

The Publisher/Subscriber idiom is well known in OOP circles for its ability to allow communication between objects without inducing tight coupling between said objects. This idiom is also generally known as a Callback system, and has been implemented in various flavors by many different libraries. This TR2 Proposal describes an implementation for a type-safe Publisher/Subscriber library.

One example where this idiom is well suited is in the design of a GUI library. The GUI library provides widgets on screen for user interaction. In order for a library client to respond to user input, it must have some way of receiving and acting on user-generated GUI events.

Many possibilities exist, for example one could require user code to derive each widget to specialize the behavior. For example:

class TextWidget;

class MyDateEntry : public TextWidget {
  // override the text entry function
  void TextEntry(char c) {
    if(c == SPECIAL_CHAR){
      // Do something special
	}else{ 
      TextWidget::TextEntry()
    }
  }

  // Many other overrides
};

This method introduces tight coupling between the client code and the GUI widget classes. As such, it becomes very brittle, and further development of the GUI is strongly confined by existing implementation details.

In contrast, Publisher/Subscriber system provides the GUI library a way to communicate with the GUI library client without inducing strong coupling. The Publisher/Subscriber library provides a way to abstract the events to the basic function signature, and allows any client to subscribe to a Publisher as long as they meet the function signature requirements. Through the use of an intelligent Subscriber proxy object, ptr-to-function, ptr-to-member-function, and function-object are all opaque to the Publisher/Subscriber mechanism. For example:

class TextWidget;

class MyDateEntry {
  void TextEntry(char c) {
    // do special stuff here
  }

  void Init() {
    TextWidget* widg = GrabOrCreateWidget();
    widg->text_entry_signal()->
        connect(std::subscriber(*this, &MyDateEntry::TextEntry));
  }
};

This design reduces the amount of coupling between TextWidget and MyDateEntry classes and limits it to the definition of the TextWidget::*_signal() Publisher objects defined by TextWidget.

Coalescing return values

Talk about Accumulators.

Tracking and automatic disconnection

Talk about trackable, why we want it, etc.

Existing practice

There have been a number of implementations of a Signal/Slot library, notably the Callback library by Rich Hickey, Qt's addition of signal/slot as C++ "keywords", libsigc++2 by Murray Cumming and Martin Schulze, Boost.Signals by Douglas Gregor. We'll summarize best existing practice by looking at libsigc++2, Boost.Signals, as well as look at the commonalities with .NET delegates, and the tr1::function class.

libsigc++2 and Boost.Signals are implemented very similarly, having both grown out of the earlier libsigc++1.2 library written by Karl Nelson and Tero Pulkkinen. The major concepts of these two libraries are:

• signal<> object which acts as a publisher to provide messages (really function calls) to a list of subscribers (slot<> objects)
• slot<> object which provides an interface to a function, whether it be a member function, ptr-to-function, or function object. The slot<> provides the abstraction to the basic function signature -- return value and argument list.
• connection object which represents a signal/slot registration, allowing the programmer to disconnect a slot<> from a signal<>
• trackable base class, which provides the mechanism for automatic signal/slot disconnection when the object is destructed.

libsigc++

sigc::signal<R,Arg1,Arg2,...,ArgN>

signal<> object is templatized in terms of a return value
type R, and an arbitrary number of argument types
Arg1..N.  The signal<> object provides
facilities to:

• connect() a slot<> object
• emit(Arg1,Arg2,...,ArgN) a signal to each of it's connected slot<> objects
• note the return value of the last slot, or marshall all return values into a container, and return the result(s) back to the caller of emit()
• make_slot() provides a slot<> object suitable for connection to another signal<> to provide signal-to-signal connection.
• provide access to the list of slots, for slot reordering

sigc::slot<R,Arg1,Arg2,...,ArgN>

slot<> object is templatized in terms of a return value type R, and an arbitrary number of argument types Arg1..N. The slot<> object provides facilities to:

• encapsulate a function call to either a ptr-to-function using sigc::ptr_fun(), or ptr-to-member-function, or function object using sigc::mem_fun()
• pass the arguments Arg1..N to the function it is wrapping
• pass the return value of the function back to the caller

sigc::connection

connection object encapsulates an existing signal/slot connection. The connection provides facilities to:

• disconnect() the slot<> object from the signal<>
• temporarily block() the signal<> from calling the slot<>
• unblock() the slot<> to resume calling the slot<>
• check whether a connection is really connected or not

sigc::trackable

trackable object provides a base class for objects which
either contain signal<> objects or are connected via
slot<> objects.  The trackable object
provides facilities to:

• automatically disconnect associated signal<> or slot<> objects upon destruction.
• check whether a connection is really connected or not

Boost.Signals

boost::signals::signal<R (Arg1,Arg2,...,ArgN)>

signal<> object is templatized in terms of a function
signature with an arbitrary number of argument types
Arg1..N.  The signal<> object provides
facilities to:

• connect() a slot<> object
• emit(Arg1,Arg2,...,ArgN) a signal to each of it's connected slot<> objects
• note the return value of the last slot, or marshall all return values into a container, and return the result(s) back to the caller of emit()
• group slot<> objects in logical groups for ordering slot<>

boost::signals::slot<R (Arg1,Arg2,...,ArgN)>

slot<> object is templatized in terms of a function
signature with an arbitrary number of argument types
Arg1..N.  The slot<> object provides
facilities to:

• encapsulate a function call to either a ptr-to-function or function object. If using a ptr-to-member-function, boost::bind must be used to bind the class object to the ptr-to-member-function
• pass the arguments Arg1..N to the function it is wrapping
• pass the return value of the function back to the caller

boost::signals::connection

connection object encapsulates an existing signal/slot
connection.  The connection provides facilities to:

• disconnect() the slot<> object from the signal<>

boost::signals::trackable

trackable object provides a base class for objects which
either contain signal<> objects or are connected via
slot<> objects.  The trackable object
provides facilities to:

• automatically disconnect associated signal<> or slot<> objects upon destruction.

.NET delegates

tr1::function

Impact on the standard

Very little to say here, probably.

Proposed text

Unresolved Issues

Number of Arguments

The number of arguments allowed to a signal will be fixed to some arbitrary number. Given that someone somewhere will find that limit inadequate, no matter what limit is chosen, some easy mechanism might be chosen to allow the user to define a signal/slot combination with the desired number of arguments.

libsigc++2 provides this capability in the form of m4 macros which can be processed into a header file form.

Boost.Signals implements the signal/slot objects in terms of preprocessor macros, allowing easy customization.

Slot<> Grouping

Boost.Signals provides a mechanism for grouping slots in some logical orderly fashion. It has been shown in the Boost.Signals implementation that this feature causes pain in the implementation, and the author has expressed a desire to drop this feature from the TR2 proposal. Perhaps there is a way to build a grouping mechanism in "user space" code, utilizing a signal-to-signal connection capability as is provided in libsigc++2.

References

---

dgregor

Last modified: Tue Jul 26 15:43:05 EST 2005

cjnygard

Last modified: Tue Aug 2 13:06:14 EST 2005

* added Existing Practice for libsigc++2 and Boost.Signals, with some commentary
* added section for Unresolved Issues, with entries for number of args and grouping
* added  to Motivation, expecting rough treatment editorially