rpc: add pub/sub support

rpc/doc.go

@@ -68,35 +68,19 @@ The package also supports the publish subscribe pattern through the use of subsc
 A method that is considered eligible for notifications must satisfy the following criteria:
  - object must be exported
  - method must be exported
+ - first method argument type must be context.Context
  - method argument(s) must be exported or builtin types
  - method must return the tuple Subscription, error
 
-
 An example method:
- func (s *BlockChainService) Head() (Subscription, error) {
- 	sub := s.bc.eventMux.Subscribe(ChainHeadEvent{})
-	return v2.NewSubscription(sub), nil
- }
-
-This method will push all raised ChainHeadEvents to subscribed clients. If the client is only
-interested in every N'th block it is possible to add a criteria.
-
- func (s *BlockChainService) HeadFiltered(nth uint64) (Subscription, error) {
- 	sub := s.bc.eventMux.Subscribe(ChainHeadEvent{})
-
-	criteria := func(event interface{}) bool {
-		chainHeadEvent := event.(ChainHeadEvent)
-		if chainHeadEvent.Block.NumberU64() % nth == 0 {
-			return true
-		}
-		return false
-	}
-
-	return v2.NewSubscriptionFiltered(sub, criteria), nil
+ func (s *BlockChainService) NewBlocks(ctx context.Context) (Subscription, error) {
+ 	...
  }
 
 Subscriptions are deleted when:
  - the user sends an unsubscribe request
- - the connection which was used to create the subscription is closed
+ - the connection which was used to create the subscription is closed. This can be initiated
+   by the client and server. The server will close the connection on an write error or when
+   the queue of buffered notifications gets too big.
 */
 package rpc