TrueCloudLab/neo-go
8
0
Fork 0
mirror of https://github.com/nspcc-dev/neo-go.git synced 2024-12-03 13:58:37 +00:00
Code Issues Projects Releases Packages Wiki Activity

rpcclient: adjust new subscriptions API doc

Browse source 
Add a warning about consequences of unproper notifications reading.
Ref. https://github.com/morphbits/neofs-cdn-edge-manager/pull/88#discussion_r1088007680.
This commit is contained in:
Anna Shaleva 2023-01-30 14:35:10 +03:00
parent b56dff2b1e
commit 51a28fac8d
1 changed files with 22 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

39
pkg/rpcclient/wsclient.go
View file

@ -661,7 +661,8 @@ func (c *WSClient) SubscribeForNewBlocks(primary *int) (string, error) {
// ReceiveBlocks registers provided channel as a receiver for the new block events. // 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. // 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 // The receiver channel must be properly read and drained after usage in order not
// to block other notification receivers. Make sure you're not changing the received // to block other notification receivers. Failing to do so will cause WSClient to
// block even regular requests. Make sure you're not changing the received
// blocks, as it may affect the functionality of other notification receivers. // blocks, as it may affect the functionality of other notification receivers.
// If multiple subscriptions share the same receiver channel, then matching // If multiple subscriptions share the same receiver channel, then matching
// notification is only sent once per channel. The receiver channel will be closed // notification is only sent once per channel. The receiver channel will be closed
@ -708,7 +709,8 @@ func (c *WSClient) SubscribeForNewTransactions(sender *util.Uint160, signer *uti
// ReceiveTransactions registers provided channel as a receiver for new transaction // 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 // 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 // filter. The receiver channel must be properly read and drained after usage in
// order not to block other notification receivers. Make sure you're not changing // order not to block other notification receivers. Failing to do so will cause
// WSClient to block even regular requests. Make sure you're not changing
// the received transactions, as it may affect the functionality of other // the received transactions, as it may affect the functionality of other
// notification receivers.If multiple subscriptions share the same receiver channel, // notification receivers.If multiple subscriptions share the same receiver channel,
// then matching notification is only sent once per channel. The receiver channel // then matching notification is only sent once per channel. The receiver channel
@ -756,13 +758,13 @@ func (c *WSClient) SubscribeForExecutionNotifications(contract *util.Uint160, na
// ReceiveExecutionNotifications registers provided channel as a receiver for execution // ReceiveExecutionNotifications registers provided channel as a receiver for execution
// events. Events can be filtered by the given NotificationFilter, nil value doesn't add // 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 // any filter. The receiver channel must be properly read and drained after usage in
// order not to block other notification receivers. Make sure you're not changing the // order not to block other notification receivers. Failing to do so will cause WSClient
// received notification events, as it may affect the functionality of other // to block even regular requests. Make sure you're not changing the received notification
// notification receivers. If multiple subscriptions share the same receiver channel, // events, as it may affect the functionality of other notification receivers. If multiple
// then matching notification is only sent once per channel. The receiver channel will // subscriptions share the same receiver channel, then matching notification is only sent
// be closed by the WSClient immediately after MissedEvent is received from the server; // once per channel. The receiver channel will be closed by the WSClient immediately after
// no unsubscription is performed in this case, so it's the user responsibility to // MissedEvent is received from the server; no unsubscription is performed in this case,
// unsubscribe. // so it's the user responsibility to unsubscribe.
func (c *WSClient) ReceiveExecutionNotifications(flt *neorpc.NotificationFilter, rcvr chan<- *state.ContainedNotificationEvent) (string, error) { func (c *WSClient) ReceiveExecutionNotifications(flt *neorpc.NotificationFilter, rcvr chan<- *state.ContainedNotificationEvent) (string, error) {
if rcvr == nil { if rcvr == nil {
return "", ErrNilNotificationReceiver return "", ErrNilNotificationReceiver
@ -808,7 +810,8 @@ func (c *WSClient) SubscribeForTransactionExecutions(state *string) (string, err
// application execution result events generated during transaction execution. // application execution result events generated during transaction execution.
// Events can be filtered by the given ExecutionFilter, nil value doesn't add any filter. // 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 // The receiver channel must be properly read and drained after usage in order not
// to block other notification receivers. Make sure you're not changing the received // to block other notification receivers. Failing to do so will cause WSClient to
// block even regular requests. Make sure you're not changing the received
// execution results, as it may affect the functionality of other notification // execution results, as it may affect the functionality of other notification
// receivers. If multiple subscriptions share the same receiver channel, then // receivers. If multiple subscriptions share the same receiver channel, then
// matching notification is only sent once per channel. The receiver channel will // matching notification is only sent once per channel. The receiver channel will
@ -863,8 +866,9 @@ func (c *WSClient) SubscribeForNotaryRequests(sender *util.Uint160, mainSigner *
// where sender corresponds to notary request sender (the second fallback transaction // where sender corresponds to notary request sender (the second fallback transaction
// signer) and signer corresponds to main transaction signers. nil value doesn't add // 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 // any filter. The receiver channel must be properly read and drained after usage in
// order not to block other notification receivers. Make sure you're not changing the // order not to block other notification receivers. Failing to do so will cause
// received notary requests, as it may affect the functionality of other notification // WSClient to block even regular requests. 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 // 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 // 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 // the WSClient immediately after MissedEvent is received from the server; no
@ -889,7 +893,8 @@ func (c *WSClient) ReceiveNotaryRequests(flt *neorpc.TxFilter, rcvr chan<- *resu
// error in case if there's no subscription with the provided ID. Call to Unsubscribe // error in case if there's no subscription with the provided ID. Call to Unsubscribe
// doesn't block notifications receive process for given subscriber, thus, ensure // doesn't block notifications receive process for given subscriber, thus, ensure
// that subscriber channel is properly drained while unsubscription is being // that subscriber channel is properly drained while unsubscription is being
// performed. You may probably need to run unsubscription process in a separate // performed. Failing to do so will cause WSClient to block even regular requests.
// You may probably need to run unsubscription process in a separate
// routine (in parallel with notification receiver routine) to avoid Client's // routine (in parallel with notification receiver routine) to avoid Client's
// notification dispatcher blocking. // notification dispatcher blocking.
func (c *WSClient) Unsubscribe(id string) error { func (c *WSClient) Unsubscribe(id string) error {
@ -901,10 +906,10 @@ func (c *WSClient) Unsubscribe(id string) error {
// time and tries to unsubscribe from us many feeds as possible returning the // time and tries to unsubscribe from us many feeds as possible returning the
// chunk of unsubscription errors afterwards. Call to UnsubscribeAll doesn't block // chunk of unsubscription errors afterwards. Call to UnsubscribeAll doesn't block
// notifications receive process for given subscribers, thus, ensure that subscribers // notifications receive process for given subscribers, thus, ensure that subscribers
// channels are properly drained while unsubscription is being performed. You may // channels are properly drained while unsubscription is being performed. Failing to
// probably need to run unsubscription process in a separate routine (in parallel // do so will cause WSClient to block even regular requests. You may probably need
// with notification receiver routines) to avoid Client's notification dispatcher // to run unsubscription process in a separate routine (in parallel with notification
// blocking. // receiver routines) to avoid Client's notification dispatcher blocking.
func (c *WSClient) UnsubscribeAll() error { func (c *WSClient) UnsubscribeAll() error {
c.subscriptionsLock.Lock() c.subscriptionsLock.Lock()
subs := make([]string, 0, len(c.subscriptions)) subs := make([]string, 0, len(c.subscriptions))