You may need to use a “Lock Critical Block of Code (lock(object){…})” action if you have any trading logic in any section other than the “Input Parameters”, “Internal Variables”, “When Bar Updates”, and “Money Management” sections.
The NinjaTrader® Desktop platform is a multi-threaded application that is able to run the NinjaScript® strategies you create using Quagensia® N Edition on multiple threads at once. For instance, while the trading logic in your Quagensia N Edition Strategy’s “When Bar Updates” section is running, NinjaTrader® can process information about your NinjaScript® strategy’s orders, fills, positions, account, and much more on multiple separate threads at the same time. As another example, when you click a Button Control that your Quagensia N Edition Strategy adds to the NinjaTrader® chart on which it is applied, the trading logic that is in the Button Control’s “When Button Control is Clicked” section can be executed at the same time that everything described in the previous sentence is occurring.
The benefits of the NinjaTrader® Desktop platform being a multi-threaded application are absolutely massive in terms of the speed at which NinjaTrader® can process your strategy’s trading logic, but the fact that different parts of your trading logic can execute at the same time as one another and at the same time that NinjaTrader® is processing your running strategy internally means that you may need to place some of your logic in “Lock Critical Block of Code (lock(object){…})” blocks and take other precautions to reduce the odds that your strategy encounters problems due to the multi-threaded environment in which your strategy is running.
Multi-threaded programming is an advanced topic, different types of issues can occur due to your code and the NinjaTrader® Desktop platform’s code executing on multiple threads at once, and different issues require different advanced programming techniques. This help page shows how to use a very specific technique, completely without code in Quagensia N Edition, to protect yourself from one source of issues that can be caused by multi-threading, and is not intended to be a comprehensive manual on multi-threaded programming and all the types of issues that can occur in your strategies due to the multi-threaded nature of NinjaTrader®. If you want to learn more about multi-threaded programming than this help page offers, you can read the web pages linked to at the top of this web page, in the “Related” section, including one from the official NinjaTrader website titled “Multi-Threading Consideration for NinjaScript“, one from the official Microsoft website titled “The lock statement – ensure exclusive access to a shared resource“, and one web page from csharptutorial.net that has an excellent example of a “race condition” that the protective technique on this web page is intended to protect your strategy from encountering.
The purpose of this help page is to explain how you can use one of these techniques to ensure that a specific block of trading logic in your strategy is not executed until it can get an “exclusive lock” on a Quagensia N Edition “Lock Object” at which point no other blocks of trading logic on any other thread that also require obtaining an “exclusive lock” on the same Quagensia N Edition “Lock Object”
How to Use a “Lock Critical Block of Code (lock(object){…})” Action and a “Lock Object” to Ensure that Certain Blocks of Trading Logic are Never Executed at the Same Time on Two Different Threads, But Instead “Take Turns” Executing
If you have multiple blocks of no-code trading logic in a Quagensia N Edition Strategy that absolutely must not be executed at the exact same time as each other on two different threads, you can accomplish this by putting each of the multiple blocks of code inside of their own “Lock Critical Block of Code (lock(object){…})” Action blocks, similar to how you can put trading logic into an “If Block”.
To create a “Lock Critical Block of Code (lock(object){…})” Action block containing one of the multiple blocks of trading logic, follow these steps:
First, create an Internal Variable of Type “Lock Object” in the “Internal Variables” section of your Quagensia N Edition Strategy. You can find the “Lock Object” in the hierarchical drop-down list of data types that opens when you click on the “Type” drop-down list of an Internal Variable by navigating to this drop-down list’s “Advanced Data Types >> NinjaScript®/Advanced Objects” folder.
Second, add a “Lock Critical Block of Code (lock(object){…})” Action block directly above or below the Actions you want to be protected by the “Lock Critical Block of Code (lock(object){…})” Action block. You can find the “Lock Critical Block of Code (lock(object){…})” Action in the “More Actions” folder of the context menu that opens when you click on a location where this Action is allowed.
Third, click on the “(Not Set)” label between the large label that reads “Once an exclusive lock is obtained on the Lock Object below…” and the large label that reads “Do not release the lock until the following actions are completed…”, and select the Lock Object Internal Variable created in the first step above the way you would normally select an Internal Variable.
Fourth, cut the Actions you want to be protected by the “Lock Critical Block of Code (lock(object){…})” Action block from where they currently are located and paste them into the “Lock Critical Block of Code (lock(object){…})” Action block. You can do this using a multi-action cut followed by a multi-action paste. You can also add Actions to the inside of the “Lock Critical Block of Code (lock(object){…})” Action block the way you would normally add Actions to locations in a Quagensia N Edition Strategy where Actions are allowed.
Then, repeat the four-step process above for each additional block of trading logic that must not be executed at the exact same time as each other on two different threads. Once you do this using the same “Lock Object” Internal Variable, you can be confident that each of the multiple blocks of trading logic protected in this way, with the same “Lock Object” Internal Variable, will never execute at the same time in the same running instance of the same strategy, but instead will take turns, waiting until they can each obtain an “exclusive lock” on the same “Lock Object” Internal Variable to execute their individual blocks of trading logic, which will only occur once none of the other “Lock Critical Block of Code (lock(object){…})” Action blocks that use the same “Lock Object” Internal Variable have an “exclusive lock” on the same “Lock Object” Internal Variable. Note that if you have two instances of the same Quagensia N Edition Strategy running in NinjaTrader® at the same time, for instance by running the same strategy on two separate charts, this technique will still allow the trading logic protected in this way to run at the same time in the two separate instances of the same strategy running on two separate charts, as it only stops multiple blocks of trading logic in the same instance of the same strategy from being executed at the same time on two different threads.
By following the procedure above, you will be able to protect your strategy from a major source of multi-threading issues that can cause threading exceptions, runtime errors, and logic errors.
Two Common Types of Trading Logic that Should Be Protected Using “Lock Critical Block of Code (lock(object){…})” Actions to Ensure that They are Never Executed at the Same Time on Two Different Threads, But Instead “Take Turns” Executing
There are many types of trading logic that should be protected using “Lock Critical Block of Code (lock(object){…})” Actions to ensure that they are never executed at the same time as another block of trading logic on two different threads, but instead “take turns” executing, but two stand out as being particularly common in Quagensia N Edition Strategies:
First, if you use the same 1) Array Internal Variable, 2) List Internal Variable (not a “List of Choices” that is displayed as a drop-down lists, but a List of values like Decimal Numbers, similar to an Array), or 3) Editable Time Series Internal Variable, or 4) are using the same “Table of Data”, in two separate sections of a Quagensia N Edition Strategy whose trading logic may be executed on two different threads, such as the common scenario of using the same instance of one of these “collections” of data in both the “When Bar Updates” section and a “When Button Control is Clicked” section of a Quagensia N Edition Strategy, you probably should use the procedure detailed earlier on this page to ensure that the specific collection of data is not being changed on one thread and at the same time being either changed or accessed in any way in a different thread.
Second, even if you are not using any of the collections of data described directly above, but instead are changing a variable’s value in one section of your Quagensia N Edition Strategy and are also either reading or changing its value in a different section of your Quagensia N Edition Strategy that may execute on two different threads at the same time, you very well may need to use the procedure detailed earlier on this page to ensure that the specific blocks of trading logic in which the variable may be changed or read are not being executed at the same time. A good example of trading logic of this type that might need to be protected in this way is one where a “race condition” would otherwise occur. To see one of the best explained and simplest possible examples of a race condition in C# code (C# is the base language of NinjaScript®), check out the example on this web page from csharptutorial.net that has an excellent example of a “race condition”. Note that the “Lock Critical Block of Code (lock(object){…})” Action uses the same “lock(object) {…}” C# code syntax as in the example above.
How an Advanced NinjaScript® Programmer with Advanced Needs Can Lock on Objects Other Than “Lock Object” Internal Variables in a Quagensia N Edition Strategy
If you are an advanced NinjaScript® programmer who wants to lock on an object other than a Quagensia N Edition Strategy’s “Lock Object” Internal Variable, you can do this by following the procedure below. Note that you should only use the advanced procedure below rather that the much simpler, 100% no-code procedure above if you’ve read the instructions above and are enough of an expert to know that you have a special case that you would prefer to handle by locking on an object other than a no-code “Lock Object” Internal Variable.
If you have multiple blocks of no-code trading logic in a Quagensia N Edition Strategy that absolutely must not be executed at the exact same time as each other on two different threads, you can accomplish this by putting each of the multiple blocks of code inside of their own “Lock Critical Block of Code (lock(object){…})” Action blocks, similar to how you can put trading logic into an “If Block”.
To create a “Lock Critical Block of Code (lock(object){…})” Action block containing one of the multiple blocks of trading logic and that acquires its exclusive lock on an arbitrary object instead of a no-code “Lock Object” Internal Variable, follow these steps:
First, add a “Lock Critical Block of Code (lock(object){…})” Action block directly above or below the Actions you want to be protected by the “Lock Critical Block of Code (lock(object){…})” Action block. You can find the “Lock Critical Block of Code (lock(object){…})” Action in the “More Actions” folder of the context menu that opens when you click on a location where this Action is allowed.
Second, click on the “(Not Set)” label between the large label that reads “Once an exclusive lock is obtained on the Lock Object below…” and the large label that reads “Do not release the lock until the following actions are completed…”, and select “Raw Code Output Expression” in the “More Expressions” folder of the context menu that opens to insert a “Raw Code Output Expression” at that location. Don’t change the value of the “Raw Code Output Expression of Type” drop-down list from its default value of “Lock Object”, regardless of the data type of the object on which you want to acquire the exclusive lock.
Third, if you want the exclusive lock to be on one of the no-code Internal Variables of your Quagensia N Edition Strategy, right click in the multi-line text box of the “Raw Code Output Expression” and select the no-code Internal Variable from the context menu that appears to insert a reference to the no-code Internal Variable of your Quagensia N Edition Strategy. If you want the exclusive lock to be on an object that is not one of the no-code Internal Variables of your Quagensia N Edition Strategy, just enter the case-sensitive name of the object on which the exclusive lock should be acquired into the text box instead of selecting the no-code Internal Variable from the aforementioned context menu.
Fourth, cut the Actions you want to be protected by the “Lock Critical Block of Code (lock(object){…})” Action block from where they currently are located and paste them into the “Lock Critical Block of Code (lock(object){…})” Action block. You can do this using a multi-action cut followed by a multi-action paste. You can also add Actions to the inside of the “Lock Critical Block of Code (lock(object){…})” Action block the way you would normally add Actions to locations in a Quagensia N Edition Strategy where Actions are allowed.
Then, repeat the four-step process above for each additional block of trading logic that must not be executed at the exact same time as each other on two different threads. Once you do this using the same object in each of the “Raw Code Output Expression” text boxes, and if you are an advanced NinjaScript® programmer who fully understands the more advanced issues involving locking on different types of objects and the problems that can occur when locking on an object other than a dedicated object that is always non-null and never reset while a NinjaScript® strategy is running on market data and used for no other purpose than as a lock object, then each of the multiple blocks of trading logic protected in this way, with the same arbitrary lock object, should not execute at the same time in the same running instance of the same strategy, but instead should take turns, waiting until they can each obtain an “exclusive lock” on the same arbitrary object to execute their individual blocks of trading logic, which should only occur once none of the other “Lock Critical Block of Code (lock(object){…})” Action blocks that use the same arbitrary object have an “exclusive lock” on the same arbitrary object. Note that if you have two instances of the same Quagensia N Edition Strategy running in NinjaTrader® at the same time, for instance by running the same strategy on two separate charts, this technique will still allow the trading logic protected in this way to run at the same time in the two separate instances of the same strategy running on two separate charts (unless as an advanced NinjaScript® programmer you chose to define the arbitrary object used for the exclusive lock as a “static” member variable), as it only stops multiple blocks of trading logic in the same instance of the same strategy from being executed at the same time on two different threads.
By following the procedure above, you will be able to protect your strategy from a major source of multi-threading issues that can cause threading exceptions, runtime errors, and logic errors.
Miscellaneous Advice and Notes for the Vast Majority of Quagensia N Edition Users Who are Not Advanced NinjaScript® Programmers
- Use the four-step no-code technique that uses the no-code “Lock Critical Block of Code (lock(object){…})” Action to protect your blocks of code rather than the advanced C# technique described in the section directly above.
- If you ever suspect that you may need to use more than a single “Lock Object” internal variable, be warned: it is very easy to accidentally create trading logic that is susceptible to what are called “deadlocks” if you do this, because if done improperly a scenario can arise where one thread has an exclusive lock on “Lock Object A” and is waiting to obtain an exclusive lock on “Lock Object B” but a second thread has an exclusive lock on “Lock Object B” and is waiting to obtain an exclusive lock on “Lock Object A” so both threads end up waiting indefinitely, and this will not just stop your strategy from running but will likely cause NinjaTrader® to freeze. To learn more about “deadlocks” and how to prevent them, please read the web pages linked to in the “Relevant:” section at the top of this web page and search for the phrase “C# lock deadlock” in a search engine.
- While C#, the underlying language on which the NinjaScript® API is based, supports locking on all kinds of “objects”, Quagensia N Edition’s no-code “Lock Object” was intentionally designed to be used for no other purpose than as an object that is used in the Quagensia N Edition “Lock Critical Block of Code (lock(object){…})” Action and on which an “exclusive lock” is obtained, and the “Lock Critical Block of Code (lock(object){…})” Action was intentionally designed to only allow Internal Variables of type “Lock Object” as the object on which its “exclusive lock” is obtained in order to protect the vast majority of Quagensia N Edition Users who are not advanced NinjaScript® programmers from logic errors that can occur when attempting to get a lock on other kinds of objects, such as Text (which one should never do), an object that has a null value, objects that may be set to null, and similar kinds of objects that would lead to difficult to troubleshoot, hard to reproduce, intermittent logic errors and runtime errors (also called “exceptions”).
- A note for advanced NinjaScript® programmers: The “Lock Object” Internal Variables in Quagensia N Edition Strategies are “instance members”, not “static members” of the class. If you need to create an object that allows exclusive locking beyond a single instance of a single strategy, you will have to do it the more difficult raw code way described above. You will also need to create a “static” member variable in one of the sections in the “Other Locations in the Strategy Code File to Paste NinjaScript® Code” section of your Quagensia N Edition strategy. If you know enough to understand the sentences in this point, you should have no problem adding a static member variable to one of these advanced sections.
You may need to use a “Lock Critical Block of Code (lock(object){…})” action if you have any trading logic in any section other than the “Input Parameters”, “Internal Variables”, “When Bar Updates”, and “Money Management” sections or if you are using certain types of more advanced trading logic.
The NinjaTrader® Desktop platform is a multi-threaded application that is able to run the NinjaScript® strategies you create using Quagensia® N Edition on multiple threads at once. For instance, while the trading logic in your Quagensia N Edition Strategy’s “When Bar Updates” section is running, NinjaTrader® can process information about your NinjaScript® strategy’s orders, fills, positions, account, and much more on multiple separate threads at the same time. As another example, when you click a Button Control that your Quagensia N Edition Strategy adds to the NinjaTrader® chart on which it is applied, the trading logic that is in the Button Control’s “When Button Control is Clicked” section can be executed at the same time that everything described in the previous sentence is occurring.
The benefits of the NinjaTrader® Desktop platform being a multi-threaded application are absolutely massive in terms of the speed at which NinjaTrader® can process your strategy’s trading logic, but the fact that different parts of your trading logic can execute at the same time as one another and at the same time that NinjaTrader® is processing your running strategy internally means that you may need to place some of your logic in “lock blocks” and take other precautions to reduce the odds that your strategy encounters problems due to the multi-threaded environment in which your strategy is running.
Multi-threaded programming is an advanced topic, different types of issues can occur due to your code executing on multiple threads at once, and different issues require different advanced programming techniques. This help page shows how to use a very specific technique, completely without code in Quagensia N Edition, to protect yourself from multi-threading issues, and is not intended to be a comprehensive manual on multi-threaded programming and all types of issues that can occur in your strategies due to the multi-threaded nature of NinjaTrader®. If you want to learn more about multi-threaded programming than this help page offers you can read the web pages linked to at the top of this web page, it the “Related” section of links, including one from the official NinjaTrader website titled “Multi-Threading Consideration for NinjaScript” and one from the official Microsoft website titled “The lock statement – ensure exclusive access to a shared resource“, as well as one web page from csharptutorial.net that has an excellent example of a “race condition” that can occur without using the protective technique described on this web page.
The purpose of this help page is to explain how you can use one of these techniques to ensure that a specific block of trading logic in your strategy is not executed until it can get an “exclusive lock” on a Quagensia N Edition “Lock Object” at which point no other blocks of trading logic on any other thread that also require obtaining an “exclusive lock” on the same Quagensia N Edition “Lock Object”
The logic in a strategy’s “When Bar Updates” section, the logic in the “When Button Control is Clicked” subsection of a Control’s “Control” section, and the logic in the sections located in the “When Advanced NinjaScript® Events Occur” section execute on different threads (or at least may execute on different threads), so care must be taken to avoid threading exceptions, runtime errors, and logic errors when using certain types of trading logic in a combination of any two sections. Furthermore,
if using the same object of certain advanced data types in certain ways in both of these locations in the same strategy.
Specifically, if you use the same 1) Array Internal Variable, 2) List Internal Variable (not a “List of Choices” that is displayed as a drop-down lists, but a List of values like Decimal Numbers, similar to an Array), or 3) Editable Time Series Internal Variable, or 4) are using the same “Table of Data”, in both the “When Button Control is Clicked” subsection of a Control’s “Control” section, which executes on the UI thread, and in the “When Bar Updates” section, which does not execute on the UI thread, in the same strategy, then threading exceptions, runtime errors, or logic errors can occur if your strategy modifies the Array, List, Editable Time Series, or Table of Data in one of these two locations running on one thread, when at the same time your strategy attempts to access or modify the same exact object of one of these four types in the other of these two locations on another thread unless you put both sets of trading logic in proper “lock” blocks.
In a future version of Quagensia N Edition, there will likely be a “no-code lock block” just like Quagensia N Edition currently has no-code blocks for “Conditional Trading Logic (If-Then-Else)”, and you will be able to use them in the same was as “Conditional Trading Logic (If-Then-Else)” blocks.
However, until there is a “no-code lock block” built into Quagensia N Edition, you will need to do it the hard way, using actual code in two separate “Raw Code Output (Single or Multiple Statements)” components, one above each of the relevant trading logic and one below each of the relevant trading logic.
You can add a “Raw Code Output (Single or Multiple Statements)” component to a Quagensia Strategy by clicking on a location where an Action can go, navigating to the “More Actions…” context menu folder in the context menu that appears, and selecting the “Raw Code Output (Single or Multiple Statements)” context menu item.
Both of the “Raw Code Output (Single or Multiple Statements)” text boxes that are placed above the relevant trading lock will be identical, and will take the form “lock (AN_OBJECT_TO_LOCK ON) {“, without the double quotes. If your Internal Variable is an Array, List, or Editable Time Series, copy and paste the “lock (AN_OBJECT_TO_LOCK ON) {” into one of the “Raw Code Output (Single or Multiple Statements)” text boxes, without the double quotes, highlight the text AN_OBJECT_TO_LOCK ON, right click, and select the Array, List, or Editable Time Series Internal Variable from the context menu that appears to replace the text AN_OBJECT_TO_LOCK ON with a reference to the Array, List, or Editable Time Series Internal Variable. Then, copy and paste the entire “Raw Code Output (Single or Multiple Statements)” text box above the other relevant location described above.
Then, below one of the locations with the relevant trading logic, add another “Raw Code Output (Single or Multiple Statements)” component, and in its text box enter a single “right parenthesis” character, i.e. “}” without the double quotes. Finally, copy and paste the entire “Raw Code Output (Single or Multiple Statements)” text box below the other relevant location described above.
To learn more about “lock statements”, see this official help page from Microsoft on the lock statement in the C# language (NinjaScript® is an API built on top of C#): https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/statements/lock
The “When NinjaTrader® ATM Strategy Callback Occurs” section is located in the “When Advanced NinjaScript® Events Occur” section of Quagensia® N Edition Strategies and is meant exclusively for advanced NinjaScript® programmers working on behalf of Quagensia N Edition users who need a Quagensia N Edition Strategy that has fundamentally different functionality than the built-in Quagensia N Edition Strategy template that allows you to enter a position based on automated entry logic you create without code and then manages the open position using one of your pre-existing NinjaTrader® ATM Strategies that you can manually interact with the way you normally interact with ATMs.
Most Quagensia N Edition users will never need to use this section. Instead, most users will likely only customize ATM-based Quagensia N Edition Strategies whose original author added the appropriate advanced logic to this section. To see an example of how this section can be used by a NinjaScript® programmer to set up a Quagensia N Edition Strategy template that other Quagensia N Edition users can make copies of and add their own custom trading logic to the less advanced sections of the copied Quagensia N Edition Strategy template, open the built-in Quagensia N Edition Strategy template that mentions ATMs in its title from the Algo Explorer on the left side of Quagensia N Edition’s main window, scroll down to the “When Advanced NinjaScript® Events Occur” section of the Quagensia N Edition Strategy, expand it to see the contracted “When NinjaTrader® ATM Strategy Callback Occurs” section, and expand the “When NinjaTrader® ATM Strategy Callback Occurs” section to view the logic in it that makes up part of the necessary structure of this strategy.
Technical Details About the “When NinjaTrader® ATM Strategy Callback Occurs” Section
The “When NinjaTrader® ATM Strategy Callback Occurs” section contains logic that is executed when the NinjaTrader® ATM Strategy technology reports back, or “calls back”, to the Quagensia® N Edition Strategy as to whether or not a NinjaTrader® ATM Strategy was successfully created by the NinjaScript® method (which is also called a “function”) named “AtmStrategyCreate()”.
The NinjaScript® AtmStrategyCreate() method is called by the no-code Quagensia N Edition Function named “Submit Entry Order with ATM Strategy Attached (Strategy’s ‘State’ Must Be ‘Real-Time’) (Advanced)”. The “Submit Entry Order with ATM Strategy Attached (Strategy’s ‘State’ Must Be ‘Real-Time’) (Advanced)” no-code function is located in the “Submit an Order >> ATM Strategies (Advanced)” folder of the context menu that appears when you click on a location where this Action function is allowed, such as anywhere in the “When Bar Updates” section of a Quagensia N Edition Strategy where an Action is allowed.
Read the AtmStrategyCreate() method’s help page at ninjatrader.com to learn more about this essential NinjaScript® function.
The NinjaScript® AtmStrategyCreate() method has the following method signature:
AtmStrategyCreate(OrderAction action, OrderType orderType, double limitPrice, double stopPrice, TimeInForce timeInForce, string orderId, string strategyTemplateName, string atmStrategyId, Action<ErrorCode, string> callback)
It is the last parameter of the AtmStrategyCreate() method, which is named “callback” in the method signature above and on the help page linked to above, that has a data type of “Action<ErrorCode, string>” and which the Quagensia N Edition Function named “Submit Entry Order with ATM Strategy Attached (Strategy’s ‘State’ Must Be ‘Real-Time’) (Advanced)” sets to a function in the generated NinjaScript® strategy code of the Quagensia N Edition Strategy. The trading logic in the “When NinjaTrader® ATM Strategy Callback Occurs” section ends up in the function definition of this function which is passed as the “callback” parameter of the NinjaScript® AtmStrategyCreate() method.
Basic Information About Using this Section
Click the “Add Trading Logic” link button at the bottom of this section to get started, or if this section already contains logic, place your mouse pointer over one of the items in this section and click either the icon that appears in the upper right of the item or click on any empty space within the item. A context menu will appear with a list of menu items containing all the things that you can do at the location where you clicked. To learn more about a given menu item, place your mouse pointer over the icon on the left of the menu item and a tooltip will appear.
To learn more about any item in this section, place your mouse pointer over the icon in the right or upper right of the item or place your mouse pointer over the label next to any editable field and a tooltip will appear.
