Documentation

Overview

    Package book defines the order book used by each Market.

    Index

    Constants

    View Source
    const (
    	// DefaultBookHalfCapacity is the default capacity of one side (buy or sell)
    	// of the order book. It is set to 2^20 orders (1 mebiorders = 1,048,576
    	// orders) per book side.
    	DefaultBookHalfCapacity uint32 = 1 << 20
    )

    Variables

    This section is empty.

    Functions

    func DisableLog

    func DisableLog()

      DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

      func GreaterByPrice

      func GreaterByPrice(bi, bj *order.LimitOrder) bool

        GreaterByPrice defines a higher priority as having a higher price rate.

        func GreaterByPriceThenTime

        func GreaterByPriceThenTime(bi, bj *order.LimitOrder) bool

          GreaterByPriceThenTime defines a higher priority as having a higher price rate, with older orders breaking any tie, then OrderID as a last tie breaker.

          func LessByPrice

          func LessByPrice(bi, bj *order.LimitOrder) bool

            LessByPrice defines a higher priority as having a lower price rate.

            func LessByPriceThenTime

            func LessByPriceThenTime(bi, bj *order.LimitOrder) bool

              LessByPriceThenTime defines a higher priority as having a lower price rate, with older orders breaking any tie, then OrderID as a last tie breaker.

              func UseLogger

              func UseLogger(logger slog.Logger)

                UseLogger uses a specified Logger to output package logging info.

                Types

                type Book

                type Book struct {
                	// contains filtered or unexported fields
                }

                  Book is a market's order book. The Book uses a configurable lot size, of which all inserted orders must have a quantity that is a multiple. The buy and sell sides of the order book are contained in separate priority queues to allow constant time access to the best orders, and log time insertion and removal of orders.

                  func New

                  func New(lotSize uint64, halfCapacity ...uint32) *Book

                    New creates a new order book with the given lot size, and optional order capacity of each side of the book. To change capacity of an existing Book, use the Realloc method.

                    func (*Book) Best

                    func (b *Book) Best() (bestBuy, bestSell *order.LimitOrder)

                      Best returns pointers to the best buy and sell order in the order book. The orders are NOT removed from the book.

                      func (*Book) BestBuy

                      func (b *Book) BestBuy() *order.LimitOrder

                        BestBuy returns a pointer to the best buy order in the order book. The order is NOT removed from the book.

                        func (*Book) BestSell

                        func (b *Book) BestSell() *order.LimitOrder

                          BestSell returns a pointer to the best sell order in the order book. The order is NOT removed from the book.

                          func (*Book) BuyCount

                          func (b *Book) BuyCount() int

                            BuyCount returns the number of buy orders.

                            func (*Book) BuyOrders

                            func (b *Book) BuyOrders() []*order.LimitOrder

                              BuyOrders copies out all buy orders in the book, sorted.

                              func (*Book) BuyOrdersN

                              func (b *Book) BuyOrdersN(N int) []*order.LimitOrder

                                BuyOrdersN copies out the N best buy orders in the book, sorted.

                                func (*Book) Clear

                                func (b *Book) Clear()

                                  Clear reset the order book with configured capacity.

                                  func (*Book) HaveOrder

                                  func (b *Book) HaveOrder(oid order.OrderID) bool

                                    HaveOrder checks if an order is in either the buy or sell side of the book.

                                    func (*Book) Insert

                                    func (b *Book) Insert(o *order.LimitOrder) bool

                                      Insert attempts to insert the provided order into the order book, returning a boolean indicating if the insertion was successful. If the order is not an integer multiple of the Book's lot size, the order will not be inserted.

                                      func (*Book) LotSize

                                      func (b *Book) LotSize() uint64

                                        LotSize returns the Book's configured lot size in atoms of the base asset.

                                        func (*Book) Order

                                        func (b *Book) Order(oid order.OrderID) *order.LimitOrder

                                          Order attempts to retrieve an order from either the buy or sell side of the book. If the order data is not required, consider using HaveOrder.

                                          func (*Book) Realloc

                                          func (b *Book) Realloc(newHalfCap uint32)

                                            Realloc changes the capacity of the order book given the specified capacity of both buy and sell sides of the book.

                                            func (*Book) Remove

                                            func (b *Book) Remove(oid order.OrderID) (*order.LimitOrder, bool)

                                              Remove attempts to remove the order with the given OrderID from the book.

                                              func (*Book) RemoveUserOrders

                                              func (b *Book) RemoveUserOrders(user account.AccountID) (removedBuys, removedSells []*order.LimitOrder)

                                                RemoveUserOrders removes all orders from the book that belong to a user. The removed buy and sell orders are returned.

                                                func (*Book) SellCount

                                                func (b *Book) SellCount() int

                                                  SellCount returns the number of sell orders.

                                                  func (*Book) SellOrders

                                                  func (b *Book) SellOrders() []*order.LimitOrder

                                                    SellOrders copies out all sell orders in the book, sorted.

                                                    func (*Book) SellOrdersN

                                                    func (b *Book) SellOrdersN(N int) []*order.LimitOrder

                                                      SellOrdersN copies out the N best sell orders in the book, sorted.

                                                      func (*Book) UnfilledUserBuys

                                                      func (b *Book) UnfilledUserBuys(user account.AccountID) []*order.LimitOrder

                                                        UnfilledUserBuys retrieves all buy orders belonging to a given user that are completely unfilled.

                                                        func (*Book) UnfilledUserSells

                                                        func (b *Book) UnfilledUserSells(user account.AccountID) []*order.LimitOrder

                                                          UnfilledUserSells retrieves all sell orders belonging to a given user that are completely unfilled.

                                                          func (*Book) UserOrderTotals

                                                          func (b *Book) UserOrderTotals(user account.AccountID) (buyAmt, sellAmt, buyCount, sellCount uint64)

                                                            UserOrderTotals returns the total amount in booked orders and the number of booked orders, for both the buy and sell sides of the book. Both amounts are in units of the base asset, and should be multiples of the market's lot size.

                                                            type OrderPQ

                                                            type OrderPQ struct {
                                                            	// contains filtered or unexported fields
                                                            }

                                                              OrderPQ is a priority queue for orders, provided as orders, based on price rate. A max-oriented queue with highest rates on top is constructed via NewMaxOrderPQ, while a min-oriented queue is constructed via NewMinOrderPQ.

                                                              func NewMaxOrderPQ

                                                              func NewMaxOrderPQ(capacity uint32) *OrderPQ

                                                                NewMaxOrderPQ is the constructor for OrderPQ that initializes an empty heap with the given capacity, and sets the default LessFn for a max heap. Use OrderPQ.SetLessFn to redefine the comparator.

                                                                func NewMinOrderPQ

                                                                func NewMinOrderPQ(capacity uint32) *OrderPQ

                                                                  NewMinOrderPQ is the constructor for OrderPQ that initializes an empty heap with the given capacity, and sets the default LessFn for a min heap. Use OrderPQ.SetLessFn to redefine the comparator.

                                                                  func (*OrderPQ) Copy

                                                                  func (pq *OrderPQ) Copy() *OrderPQ

                                                                    Copy makes a deep copy of the OrderPQ. The orders are the same; each orderEntry is new. The capacity and lessFn are the same.

                                                                    func (*OrderPQ) Count

                                                                    func (pq *OrderPQ) Count() int

                                                                      Count returns the number of orders in the queue.

                                                                      func (*OrderPQ) ExtractBest

                                                                      func (pq *OrderPQ) ExtractBest() *order.LimitOrder

                                                                        ExtractBest a.k.a. pop removes the highest priority order from the queue, and returns it.

                                                                        func (*OrderPQ) ExtractN

                                                                        func (pq *OrderPQ) ExtractN(count int) []*order.LimitOrder

                                                                          ExtractN extracts the N best orders, sorted with the lessFn. ExtractBest is called until the requested number of entries are extracted. Thus, the OrderPQ is reduced in length by count, or the length of the heap, whichever is shorter. To avoid modifying the queue, use Orders or OrdersN.

                                                                          func (*OrderPQ) HaveOrder

                                                                          func (pq *OrderPQ) HaveOrder(oid order.OrderID) bool

                                                                            HaveOrder indicates if an order is in the queue.

                                                                            func (*OrderPQ) Insert

                                                                            func (pq *OrderPQ) Insert(ord *order.LimitOrder) bool

                                                                              Insert will add an element, while respecting the queue's capacity.

                                                                              if (at capacity) or (have order already), fail
                                                                              else (not at capacity), push the order onto the heap
                                                                              

                                                                              func (*OrderPQ) Len

                                                                              func (pq *OrderPQ) Len() int

                                                                                Len is required for heap.Interface. It is not thread-safe.

                                                                                func (*OrderPQ) Less

                                                                                func (pq *OrderPQ) Less(i, j int) bool

                                                                                  Less performs the comparison priority(i) vs. priority(j). Use OrderPQ.SetLessFn to define the desired behavior for the orderEntry heap[i] and heap[j]. Less is required for heap.Interface. It is not thread-safe.

                                                                                  func (*OrderPQ) Order

                                                                                  func (pq *OrderPQ) Order(oid order.OrderID) *order.LimitOrder

                                                                                    Order retrieves any existing order in the queue with the given ID.

                                                                                    func (*OrderPQ) Orders

                                                                                    func (pq *OrderPQ) Orders() []*order.LimitOrder

                                                                                      Orders copies all orders, sorted with the lessFn. The OrderPQ is unmodified.

                                                                                      func (*OrderPQ) OrdersN

                                                                                      func (pq *OrderPQ) OrdersN(count int) []*order.LimitOrder

                                                                                        OrdersN copies the N best orders, sorted with the lessFn. To avoid modifying the OrderPQ or any of the data fields, a deep copy of the OrderPQ is made and ExtractBest is called until the requested number of entries are extracted.

                                                                                        func (*OrderPQ) PeekBest

                                                                                        func (pq *OrderPQ) PeekBest() *order.LimitOrder

                                                                                          PeekBest returns the highest priority order without removing it from the queue.

                                                                                          func (*OrderPQ) Pop

                                                                                          func (pq *OrderPQ) Pop() interface{}

                                                                                            Pop will return an interface{} that may be cast to OrderPricer (or the underlying concrete type). Use heap.Pop, ExtractBest, or RemoveOrder, not this. Pop is required for heap.Interface. It is not thread-safe.

                                                                                            func (*OrderPQ) Push

                                                                                            func (pq *OrderPQ) Push(ord interface{})

                                                                                              Push an order, which must be an OrderPricer. Use heap.Push, not this directly. Push is required for heap.Interface. It is not thread-safe.

                                                                                              func (*OrderPQ) Realloc

                                                                                              func (pq *OrderPQ) Realloc(newCap uint32)

                                                                                                Realloc changes the capacity of the OrderPQ by making a deep copy with the specified capacity. The specified capacity must not be less than current.

                                                                                                func (*OrderPQ) Reheap

                                                                                                func (pq *OrderPQ) Reheap()

                                                                                                  Reheap is a thread-safe shortcut for heap.Init(pq).

                                                                                                  func (*OrderPQ) RemoveOrder

                                                                                                  func (pq *OrderPQ) RemoveOrder(lo *order.LimitOrder) (*order.LimitOrder, bool)

                                                                                                    RemoveOrder attempts to remove the provided order from the priority queue based on it's ID.

                                                                                                    func (*OrderPQ) RemoveOrderID

                                                                                                    func (pq *OrderPQ) RemoveOrderID(oid order.OrderID) (*order.LimitOrder, bool)

                                                                                                      RemoveOrderID attempts to remove the order with the given ID from the priority queue.

                                                                                                      func (*OrderPQ) RemoveUserOrders

                                                                                                      func (pq *OrderPQ) RemoveUserOrders(user account.AccountID) (removed []*order.LimitOrder)

                                                                                                        RemoveUserOrders removes all orders from the queue that belong to a user.

                                                                                                        func (*OrderPQ) Reset

                                                                                                        func (pq *OrderPQ) Reset(orders []*order.LimitOrder)

                                                                                                          Reset creates a fresh queue given the input []OrderPricer. For every element in the queue, Reset resets the heap index. The heap is then heapified. The input slice is not modifed.

                                                                                                          func (*OrderPQ) SetLessFn

                                                                                                          func (pq *OrderPQ) SetLessFn(lessFn func(bi, bj *order.LimitOrder) bool)

                                                                                                            SetLessFn sets the function called by Less. The input lessFn must accept two *orderEntry and return a bool, unlike Less, which accepts heap indexes i, j. This allows to define a comparator without requiring a heap.

                                                                                                            func (*OrderPQ) Swap

                                                                                                            func (pq *OrderPQ) Swap(i, j int)

                                                                                                              Swap swaps the orderEntry at i and j. This is used by container/heap. Swap is required for heap.Interface. It is not thread-safe.

                                                                                                              func (*OrderPQ) UnfilledForUser

                                                                                                              func (pq *OrderPQ) UnfilledForUser(user account.AccountID) []*order.LimitOrder

                                                                                                                UnfilledForUser retrieves all completely unfilled orders for a given user.

                                                                                                                func (*OrderPQ) UserOrderTotals

                                                                                                                func (pq *OrderPQ) UserOrderTotals(user account.AccountID) (amt, count uint64)

                                                                                                                  UserOrderTotals returns the total value and number of booked orders.

                                                                                                                  func (*OrderPQ) Worst

                                                                                                                  func (pq *OrderPQ) Worst() *order.LimitOrder

                                                                                                                    Worst returns the worst order (depending on the queue's lessFn) in the queue. This is done by scanning the binary heap's leaf nodes since only the best order's position (first element) is known, while the only guarantee regarding the worst element is that it will not be another node's parent (i.e. it is a leaf node).