Subscription.unsubscribe

Unsubscribe: releases the reference held by this subscription object; the actual unsubscribe request is sent to the exchange only when the last reference is released.

    
    
    
unsubscribe()

Examples

• Subscribe to ticker, unsubscribe after receiving 10 updates, then switch to subscribing to the trade feed.

  • javascript
  • python
  • rust

  
      javascript
      
      
  function main() {
      var tk = ctx.subscribe(exchange, {channel: "ticker"})
      var n = 0
      while (n < 10) {
          var ev = ctx.poll(tk, 1000)
          if (ev && ev.kind === 1) {
              Log("ticker", ev.last)
              n++
          }
      }
      tk.unsubscribe()
  
      var trades = ctx.subscribe(exchange, {channel: "trade"})
      while (true) {
          var t = ctx.poll(trades, 1000)
          if (t && t.kind === 4) {
              Log("trade", t.tradeId, t.side, t.px, t.qty)
          }
      }
  }
  

  
      python
      
      
  def main():
      tk = ctx.subscribe(exchange, {"channel": "ticker"})
      n = 0
      while n < 10:
          ev = ctx.poll(tk, 1000)
          if ev is not None and ev.kind == 1:
              Log("ticker", ev.last)
              n += 1
      tk.unsubscribe()
  
      trades = ctx.subscribe(exchange, {"channel": "trade"})
      while True:
          t = ctx.poll(trades, 1000)
          if t is not None and t.kind == 4:
              Log("trade", t.tradeId, t.side, t.px, t.qty)
  

  
      rust
      
      
  fn main() {
      let tk = ctx::subscribe(exchange, ctx::SubOpts::ticker()).unwrap();
      let mut n = 0;
      while n < 10 {
          match ctx::poll(&[tk.id()], Some(1000)) {
              ctx::Polled::Event(_) => n += 1,
              ctx::Polled::Stopped => return,
              _ => {}
          }
      }
      tk.unsubscribe().unwrap();
      Log!("ticker unsubscribed after", n, "events");
  }
  

• A subscription belongs to the thread that created it: subscribing to the same content in a child thread yields an independent event stream, and a thread can only unsubscribe its own subscriptions; the main thread unsubscribes both streams at once through the array returned by the batch subscription.

  • javascript
  • python

  
      javascript
      
      
  function main() {
      var subs = ctx.subscribe(0, {channel: "ticker", symbol: ["BTC_USDT", "ETH_USDT"]})
      var t = threading.Thread(function() {
          // Subscribe to the same content in the thread: it gets its own event stream, with an id different from the main thread's
          var mine = ctx.subscribe(0, {channel: "ticker", symbol: "BTC_USDT"})
          var id = mine.id
          mine.unsubscribe()       // A thread can unsubscribe its own subscription
          return id
      })
      Log("main stream:", subs[0].id, "thread stream:", t.join().ret)
      subs.unsubscribe()           // The main thread unsubscribes its own two streams
  }
  

  
      python
      
      
  import threading
  
  def main():
      subs = ctx.subscribe(0, {"channel": "ticker", "symbol": ["BTC_USDT", "ETH_USDT"]})
  
      def worker():
          # Subscribe to the same content in the thread: it gets its own event stream, with an id different from the main thread's
          mine = ctx.subscribe(0, {"channel": "ticker", "symbol": "BTC_USDT"})
          Log("main stream:", subs[0].id, "thread stream:", mine.id)
          mine.unsubscribe()               # A thread can unsubscribe its own subscription
          try:
              subs[0].unsubscribe()        # The subscription belongs to the main thread, so this raises an exception
          except Exception as e:
              Log("cannot unsubscribe here:", e)
  
      t = threading.Thread(target=worker)
      t.start()
      t.join()
      subs.unsubscribe()                   # The main thread unsubscribes its own two streams
  

See Also

Remarks

Within the same thread, subscriptions with the same identity (same account, symbol, channel, depth levels and period) share a single event stream, and each call to ctx.subscribe adds one reference. unsubscribe() releases only the one reference held by this object; other subscription objects sharing the same event stream are not affected and continue to receive events normally. Identical subscriptions made in other threads also hold their own references. Only after all references have been released does the docker unsubscribe from the exchange; any events arriving after that are discarded.

Only the thread that created the subscription can unsubscribe it: calling it from another thread throws an exception (the error message contains belongs to another thread), and the subscription remains active. When a thread ends, all of its subscriptions are unsubscribed automatically.

The array returned by a batch subscription also provides an unsubscribe() method, which unsubscribes all elements of the array at once (each element releases one reference).

Calling unsubscribe() repeatedly on the same subscription object has no effect; calling it after the subscription has been rejected by the exchange (an initialization status event with prefillStatus equal to 2 was received) likewise has no effect. After unsubscribing, the object's book(), positions() and balances() methods can no longer be called.

Subscribing to the same content again after unsubscribing yields a new event stream ID.

In Python it is sub.unsubscribe(), and the SubscriptionList returned by a batch subscription also provides unsubscribe(). In Rust it is sub.unsubscribe() -> Result<(), String>, and calling it from another thread returns Err. ctx::Sub can be copied, and the reference count is based on the number of ctx::subscribe() calls: for each call to ctx::subscribe(), call unsubscribe() once; do not unsubscribe the same copied handle more than once.