303 Order, Trades and Events

Class strategy features a number of event handlers for handling order events. These are declared as virtual functions with a name that has an 'on_' prefix. They are:

By default these members do nothing. Developers must define their own overrides to respond to the events that trigger such handlers.

Tutorial 303 randomly sends market and limit orders to buy and sell. For demonstration purposes the strategy defines implementations for all order and trade related event handlers. In this case they are used exclusively to print messages to the terminal as well as a few assertions.

Since this tutorial is a little longer, we will look at each section separately. Please refer to the tutorial project to get a complete source listing.

This part is quite should be self explanatory. We generate a random number, and depending on the number we perform a particular action. Note that we retain an order reference for every order we generate. Before we assign to the order_ref object we ensure that the existing reference is not to an active order (that would cause an exception). Also recall that the order_ref::is_active() member also checks if the object is initialized at all (if not it returns false). Unless you are working with a trivial strategy the call to is_active() is essential before assigning to an order_ref object.

See the last section for a full listing of program output. When going through program output pay attention to the order in which the event handler functions are called. For example on_order_status_changed() is called before on_order_sent().

WARNING - 'Live' vs 'Simulated' Environments:

There is an important difference between a strategy that is being deployed, or tested, on 'live' data versus one that runs in simulation on data from a database table!

In a 'live' environment (when the strategy is connected to the server software), the strategy responds to incoming messages. These messages are processed one message at a time. An incoming message will be ignored if the strategy is still responding to another message. For example, if an new price record message is received, the strategy's on_bar_close() member is invoked which may send new orders to the broker/platform. These orders may be filled or rejected immediately, but the strategy won't know about it until it processes the corresponding incoming messages. This means that your code can't get confused. If an order status is 'active' in one line of code, it can't magically change to 'cancelled' in a subsequent line, even if on the exchange the order was already cancelled. This is however a technicality since under normal circumstances event handler members will be evaluated magnitudes faster than the time it takes to send and receive messages.

In a 'simulated' environment, the strategy is optimized for speed. There is no message queue at all. Hence, when order::cancel() is called, the order is cancelled immediately, and an on_order_status_change() event will interrupt the event handler that is currently being evaluated. Another difference is that in simulation, orders are filled in their entirety and so partial fills won't occur. Orders are also never rejected.

This can cause subtle and not so subtle differences in how your strategy behaves. This is why walk-forward testing in a 'live' environment is very important to verify that the strategy acts as expected.

This member is called a soon as an order was sent by any order function like instrument::buy(), before the order function returns - hence the warning message below.

// 'mkt_order' is not yet initialized as member that sent the order has not returned yet.

This member is called every time an order's status changes. Note that you can access the previous status with order_ref::prev_status().

This member is called when a transaction is confirmed. In practice you will more likely respond to on_order_filled() and on_order_partially_filled() since that saves you from having to explicitly determine whether the order was completely filled. Use the transaction::order() and transaction::instrument() members to access related objects.

This event handler is called when an order is filled in its entirety. Note that the order_ref argument is const. The order is no longer intended to be modified.

//Note: In simulation all orders are filled in their entirety - no partial fills!

This event handler is called when an order is partially filled. The order_ref argument is not constant, so that you can modify or cancel the order.

//Note: In simulation all orders are filled in their entirety - no partial fills!

Recall the definition of a trade as explained in a previous section. A trade constitutes all the buying and selling between when the trade is first opened until it is closed. A trade can thus have any number of add-on legs and partial-exit legs.

The on_trade_open() even handler is invoked when a new trade is opened. Use the instrument argument to determine if the trade is long or short.

std::cout << "A new trade has been opened for symbol: " << i.symbol() << std::endl;

The on_trade_close() member is called when a trade is closed out, either by the position going flat or via reversal. The trade_info structure holds various trade metrics describing the trade.

This member is called when an order is rejected. If information is available it can be retrieved via order_ref::reject_info() which returns a string. Rejects do not occur with standard simulations!

This handler is called when a cancel request is rejected; presumably because the order was already filled. Rejects do not occur with standard simulations!

This handler is called when a cancel-replace operation is rejected; presumably because the order was already filled. Rejects do not occur with standard simulations!

When inspecting the program's output, you will notice the long order-ids like 1000000003. Recall that order-ids are composed of the instrument-id (front) and order sequence(back). Since this strategy only has one instrument member, all order-ids start with 1.