From 28927228f027312ba1d483d363cdb46f0bf6d5e7 Mon Sep 17 00:00:00 2001 From: Anna Shaleva Date: Tue, 17 Jan 2023 17:10:10 +0300 Subject: [PATCH] *: adjust subscription-related doc Add a warning about received events modification where applicable. --- pkg/core/blockchain.go | 14 +++++-- pkg/core/mempool/subscriptions.go | 3 +- pkg/network/server.go | 3 +- pkg/rpcclient/wsclient.go | 64 ++++++++++++++++++------------- 4 files changed, 52 insertions(+), 32 deletions(-) diff --git a/pkg/core/blockchain.go b/pkg/core/blockchain.go index 4f7940a3c..b56f68b13 100644 --- a/pkg/core/blockchain.go +++ b/pkg/core/blockchain.go @@ -2142,7 +2142,8 @@ func (bc *Blockchain) GetConfig() config.Blockchain { // SubscribeForBlocks adds given channel to new block event broadcasting, so when // there is a new block added to the chain you'll receive it via this channel. // Make sure it's read from regularly as not reading these events might affect -// other Blockchain functions. +// other Blockchain functions. Make sure you're not changing the received blocks, +// as it may affect the functionality of Blockchain and other subscribers. func (bc *Blockchain) SubscribeForBlocks(ch chan *block.Block) { bc.subCh <- ch } @@ -2150,7 +2151,9 @@ func (bc *Blockchain) SubscribeForBlocks(ch chan *block.Block) { // SubscribeForTransactions adds given channel to new transaction event // broadcasting, so when there is a new transaction added to the chain (in a // block) you'll receive it via this channel. Make sure it's read from regularly -// as not reading these events might affect other Blockchain functions. +// as not reading these events might affect other Blockchain functions. Make sure +// you're not changing the received transactions, as it may affect the +// functionality of Blockchain and other subscribers. func (bc *Blockchain) SubscribeForTransactions(ch chan *transaction.Transaction) { bc.subCh <- ch } @@ -2161,7 +2164,8 @@ func (bc *Blockchain) SubscribeForTransactions(ch chan *transaction.Transaction) // successful transactions are broadcasted, if you're interested in failed // transactions use SubscribeForExecutions instead. Make sure this channel is // read from regularly as not reading these events might affect other Blockchain -// functions. +// functions. Make sure you're not changing the received notification events, as +// it may affect the functionality of Blockchain and other subscribers. func (bc *Blockchain) SubscribeForNotifications(ch chan *state.ContainedNotificationEvent) { bc.subCh <- ch } @@ -2169,7 +2173,9 @@ func (bc *Blockchain) SubscribeForNotifications(ch chan *state.ContainedNotifica // SubscribeForExecutions adds given channel to new transaction execution event // broadcasting, so when an in-block transaction execution happens you'll receive // the result of it via this channel. Make sure it's read from regularly as not -// reading these events might affect other Blockchain functions. +// reading these events might affect other Blockchain functions. Make sure you're +// not changing the received execution results, as it may affect the +// functionality of Blockchain and other subscribers. func (bc *Blockchain) SubscribeForExecutions(ch chan *state.AppExecResult) { bc.subCh <- ch } diff --git a/pkg/core/mempool/subscriptions.go b/pkg/core/mempool/subscriptions.go index 527ae370c..0188c1994 100644 --- a/pkg/core/mempool/subscriptions.go +++ b/pkg/core/mempool/subscriptions.go @@ -27,7 +27,8 @@ func (mp *Pool) StopSubscriptions() { // SubscribeForTransactions adds the given channel to the new mempool event broadcasting, so when // there is a new transactions added to the mempool or an existing transaction removed from -// the mempool, you'll receive it via this channel. +// the mempool, you'll receive it via this channel. Make sure you're not changing the received +// mempool events, as it may affect the functionality of other subscribers. func (mp *Pool) SubscribeForTransactions(ch chan<- mempoolevent.Event) { if mp.subscriptionsOn.Load() { mp.subCh <- ch diff --git a/pkg/network/server.go b/pkg/network/server.go index 9f5572e77..112ab56f4 100644 --- a/pkg/network/server.go +++ b/pkg/network/server.go @@ -552,7 +552,8 @@ func (s *Server) tryStartServices() { // broadcasting, so when a new P2PNotaryRequest is received or an existing // P2PNotaryRequest is removed from the pool you'll receive it via this channel. // Make sure it's read from regularly as not reading these events might affect -// other Server functions. +// other Server functions. Make sure you're not changing the received mempool +// events, as it may affect the functionality of Blockchain and other subscribers. // Ensure that P2PSigExtensions are enabled before calling this method. func (s *Server) SubscribeForNotaryRequests(ch chan<- mempoolevent.Event) { if !s.chain.P2PSigExtensionsEnabled() { diff --git a/pkg/rpcclient/wsclient.go b/pkg/rpcclient/wsclient.go index fec9e3d2d..e3dee9b1a 100644 --- a/pkg/rpcclient/wsclient.go +++ b/pkg/rpcclient/wsclient.go @@ -33,7 +33,9 @@ type WSClient struct { // it wants to use subscription mechanism. Failing to do so will cause // WSClient to block even regular requests. This channel is not buffered. // In case of protocol error or upon connection closure, this channel will - // be closed, so make sure to handle this. + // be closed, so make sure to handle this. Make sure you're not changing the + // received notifications, as it may affect the functionality of other + // notification receivers. // // Deprecated: please, use custom channels with ReceiveBlocks, ReceiveTransactions, // ReceiveExecutionNotifications, ReceiveExecutions, ReceiveNotaryRequests @@ -659,11 +661,13 @@ func (c *WSClient) SubscribeForNewBlocks(primary *int) (string, error) { // ReceiveBlocks registers provided channel as a receiver for the new block events. // Events can be filtered by the given BlockFilter, nil value doesn't add any filter. // The receiver channel must be properly read and drained after usage in order not -// to block other notification receivers. If multiple subscriptions share the same -// receiver channel, then matching notification is only sent once per channel. The -// receiver channel will be closed by the WSClient immediately after MissedEvent is -// received from the server; no unsubscription is performed in this case, so it's the -// user responsibility to unsubscribe. +// to block other notification receivers. Make sure you're not changing the received +// blocks, as it may affect the functionality of other notification receivers. +// If multiple subscriptions share the same receiver channel, then matching +// notification is only sent once per channel. The receiver channel will be closed +// by the WSClient immediately after MissedEvent is received from the server; +// no unsubscription is performed in this case, so it's the user responsibility +// to unsubscribe. func (c *WSClient) ReceiveBlocks(flt *neorpc.BlockFilter, rcvr chan<- *block.Block) (string, error) { if rcvr == nil { return "", ErrNilNotificationReceiver @@ -704,11 +708,13 @@ func (c *WSClient) SubscribeForNewTransactions(sender *util.Uint160, signer *uti // ReceiveTransactions registers provided channel as a receiver for new transaction // events. Events can be filtered by the given TxFilter, nil value doesn't add any // filter. The receiver channel must be properly read and drained after usage in -// order not to block other notification receivers. If multiple subscriptions share -// the same receiver channel, then matching notification is only sent once per channel. -// The receiver channel will be closed by the WSClient immediately after MissedEvent is -// received from the server; no unsubscription is performed in this case, so it's the -// user responsibility to unsubscribe. +// order not to block other notification receivers. Make sure you're not changing +// the received transactions, as it may affect the functionality of other +// notification receivers.If multiple subscriptions share the same receiver channel, +// then matching notification is only sent once per channel. The receiver channel +// will be closed by the WSClient immediately after MissedEvent is received from +// the server; no unsubscription is performed in this case, so it's the user +// responsibility to unsubscribe. func (c *WSClient) ReceiveTransactions(flt *neorpc.TxFilter, rcvr chan<- *transaction.Transaction) (string, error) { if rcvr == nil { return "", ErrNilNotificationReceiver @@ -750,11 +756,13 @@ func (c *WSClient) SubscribeForExecutionNotifications(contract *util.Uint160, na // ReceiveExecutionNotifications registers provided channel as a receiver for execution // events. Events can be filtered by the given NotificationFilter, nil value doesn't add // any filter. The receiver channel must be properly read and drained after usage in -// order not to block other notification receivers. If multiple subscriptions share the -// same receiver channel, then matching notification is only sent once per channel. The -// receiver channel will be closed by the WSClient immediately after MissedEvent is -// received from the server; no unsubscription is performed in this case, so it's the -// user responsibility to unsubscribe. +// order not to block other notification receivers. Make sure you're not changing the +// received notification events, as it may affect the functionality of other +// notification receivers. If multiple subscriptions share the same receiver channel, +// then matching notification is only sent once per channel. The receiver channel will +// be closed by the WSClient immediately after MissedEvent is received from the server; +// no unsubscription is performed in this case, so it's the user responsibility to +// unsubscribe. func (c *WSClient) ReceiveExecutionNotifications(flt *neorpc.NotificationFilter, rcvr chan<- *state.ContainedNotificationEvent) (string, error) { if rcvr == nil { return "", ErrNilNotificationReceiver @@ -800,11 +808,13 @@ func (c *WSClient) SubscribeForTransactionExecutions(state *string) (string, err // application execution result events generated during transaction execution. // Events can be filtered by the given ExecutionFilter, nil value doesn't add any filter. // The receiver channel must be properly read and drained after usage in order not -// to block other notification receivers. If multiple subscriptions share the same -// receiver channel, then matching notification is only sent once per channel. The -// receiver channel will be closed by the WSClient immediately after MissedEvent is -// received from the server; no unsubscription is performed in this case, so it's the -// user responsibility to unsubscribe. +// to block other notification receivers. Make sure you're not changing the received +// execution results, as it may affect the functionality of other notification +// receivers. If multiple subscriptions share the same receiver channel, then +// matching notification is only sent once per channel. The receiver channel will +// be closed by the WSClient immediately after MissedEvent is received from the +// server; no unsubscription is performed in this case, so it's the user responsibility +// to unsubscribe. func (c *WSClient) ReceiveExecutions(flt *neorpc.ExecutionFilter, rcvr chan<- *state.AppExecResult) (string, error) { if rcvr == nil { return "", ErrNilNotificationReceiver @@ -853,11 +863,13 @@ func (c *WSClient) SubscribeForNotaryRequests(sender *util.Uint160, mainSigner * // where sender corresponds to notary request sender (the second fallback transaction // signer) and signer corresponds to main transaction signers. nil value doesn't add // any filter. The receiver channel must be properly read and drained after usage in -// order not to block other notification receivers. If multiple subscriptions share -// the same receiver channel, then matching notification is only sent once per channel. -// The receiver channel will be closed by the WSClient immediately after MissedEvent -// is received from the server; no unsubscription is performed in this case, so it's the -// user responsibility to unsubscribe. +// order not to block other notification receivers. Make sure you're not changing the +// received notary requests, as it may affect the functionality of other notification +// receivers. If multiple subscriptions share the same receiver channel, then matching +// notification is only sent once per channel. The receiver channel will be closed by +// the WSClient immediately after MissedEvent is received from the server; no +// unsubscription is performed in this case, so it's the user responsibility to +// unsubscribe. func (c *WSClient) ReceiveNotaryRequests(flt *neorpc.TxFilter, rcvr chan<- *result.NotaryRequestEvent) (string, error) { if rcvr == nil { return "", ErrNilNotificationReceiver