event: add new Subscription type and related utilities

This commit introduces a new Subscription type, which is synonymous with
ethereum.Subscription. It also adds a couple of utilities that make
working with Subscriptions easier. The mot complex utility is Feed, a
synchronisation device that implements broadcast subscriptions. Feed is
slightly faster than TypeMux and will replace uses of TypeMux across the
go-ethereum codebase in the future.

1 files changed, 56 insertions, 0 deletions

diff --git a/event/example_subscription_test.go b/event/example_subscription_test.go
new file mode 100644
index 000000000..de1126689
--- /dev/null
+++ b/event/example_subscription_test.go
@@ -0,0 +1,56 @@
+// Copyright 2017 The go-ethereum Authors
+// This file is part of the go-ethereum library.
+//
+// The go-ethereum library 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.
+//
+// The go-ethereum library 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 the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.
+
+package event_test
+
+import (
+	"fmt"
+
+	"github.com/ethereum/go-ethereum/event"
+)
+
+func ExampleNewSubscription() {
+	// Create a subscription that sends 10 integers on ch.
+	ch := make(chan int)
+	sub := event.NewSubscription(func(quit <-chan struct{}) error {
+		for i := 0; i < 10; i++ {
+			select {
+			case ch <- i:
+			case <-quit:
+				fmt.Println("unsubscribed")
+				return nil
+			}
+		}
+		return nil
+	})
+
+	// This is the consumer. It reads 5 integers, then aborts the subscription.
+	// Note that Unsubscribe waits until the producer has shut down.
+	for i := range ch {
+		fmt.Println(i)
+		if i == 4 {
+			sub.Unsubscribe()
+			break
+		}
+	}
+	// Output:
+	// 0
+	// 1
+	// 2
+	// 3
+	// 4
+	// unsubscribed
+}