Spire Trading Inc. - User contributions [en]

ASX ITCH

2020-07-28T23:00:34Z

Kman:

Support for ASX Trade ITCH market data is provided by the AsxItchMarketDataFeedClient. This market data feed can be used by Spire to populate the security database for ASX listed securities, BBO quotes, time and sales, book quotes and order imbalances. In addition to real time market data, ASX Trade ITCH also provides a market data snapshot used for data recovery along with retransmission of dropped packets, both of which are fully supported.

For more information about the ASX ITCH protocol and connectivity, refer to https://www.asxonline.com/public/documents/asx-trade-open-interface-manuals.html

==Configuration==

By default ASX ITCH is split into multiple feeds each handling a range of securities. Each feed is placed in its own directory and named <code>asxitch_partition[N]</code> with <code>N = 1</code> representing the first feed. Each feed also has its own configuration file structured as follows:

<pre>
---
service_locator:

# The Service Locator to authenticate with.
address: 127.0.0.1:20000

# The market data feed's username.
username: market_data_feed

# The market data feed's password.
password: 1234

# Whether to log all packets.
enable_logging: false

# The market code (MIC) to publish.
market: ASX

# Whether to synthetically publish time and sales
# based on matched orders.
is_time_and_sale: true

# Specifies how frequently to publish updates to
# the market data server.
sampling: 100ms

# The multicast group to join.
host: 233.0.0.0:12345

# The network interface to use to join
# the multicast group.
interface: 192.168.0.1:30000

# The GLIMPSE host to connect to for
# snapshot retrieval.
glimpse_host: 122.100.100.1:30000

# How long to wait for a snapshot before
# timing out.
glimpse_timeout: 5s

# The GLIMPSE username.
username: glimpse101

# The GLIMPSE password.
password: 1234
...
</pre>

==Operations==

The AsxItchMarketDataFeedClient contains the standard suite of scripts used to manage each individual feed.

The <code>start.sh</code> script is used to start either a single feed by specifying the feed's unique identifier <code>partition[N]</code> as a command line argument or used to start all feeds by passing <code>all</code> as a command line argument. Similarly the <code>stop.sh</code> script is used to stop a currently running feed. The <code>list_feeds.sh</code> will output all currently running feeds and the <code>create_softlinks.sh</code> script is used when first setting up the feeds, or when a new feed is added.

On startup a log file is created with the name <code>srv_[YYYY][MM][DD]_[HH]_[MM]_[SS].log</code> and is used to record dropped packets, any error messages or warnings, and if logging is enabled in the configuration file, a dump of every received message.

ASX ITCH

2020-07-28T22:54:27Z

Kman:

Support for ASX Trade ITCH market data is provided by the AsxItchMarketDataFeedClient. This market data feed can be used by Spire to populate the security database for ASX listed securities, BBO quotes, time and sales, book quotes and order imbalances. In addition to real time market data, ASX Trade ITCH also provides a market data snapshot used for data recovery along with retransmission of dropped packets, both of which are fully supported.

==Configuration==

By default ASX ITCH is split into multiple feeds each handling a range of securities. Each feed is placed in its own directory and named <code>asxitch_partition[N]</code> with <code>N = 1</code> representing the first feed. Each feed also has its own configuration file structured as follows:

<pre>
---
service_locator:

# The Service Locator to authenticate with.
address: 127.0.0.1:20000

# The market data feed's username.
username: market_data_feed

# The market data feed's password.
password: 1234

# Whether to log all packets.
enable_logging: false

# The market code (MIC) to publish.
market: ASX

# Whether to synthetically publish time and sales
# based on matched orders.
is_time_and_sale: true

# Specifies how frequently to publish updates to
# the market data server.
sampling: 100ms

# The multicast group to join.
host: 233.0.0.0:12345

# The network interface to use to join
# the multicast group.
interface: 192.168.0.1:30000

# The GLIMPSE host to connect to for
# snapshot retrieval.
glimpse_host: 122.100.100.1:30000

# How long to wait for a snapshot before
# timing out.
glimpse_timeout: 5s

# The GLIMPSE username.
username: glimpse101

# The GLIMPSE password.
password: 1234
...
</pre>

==Operations==

The AsxItchMarketDataFeedClient contains the standard suite of scripts used to manage each individual feed.

The <code>start.sh</code> script is used to start either a single feed by specifying the feed's unique identifier <code>partition[N]</code> as a command line argument or used to start all feeds by passing <code>all</code> as a command line argument. Similarly the <code>stop.sh</code> script is used to stop a currently running feed. The <code>list_feeds.sh</code> will output all currently running feeds and the <code>create_softlinks.sh</code> script is used when first setting up the feeds, or when a new feed is added.

On startup a log file is created with the name <code>srv_[YYYY][MM][DD]_[HH]_[MM]_[SS].log</code> and is used to record dropped packets, any error messages or warnings, and if logging is enabled in the configuration file, a dump of every received message.

ASX ITCH

2020-07-28T18:04:02Z

Kman: Created page with "Support for ASX Trade ITCH market data is provided by the AsxItchMarketDataFeedClient. This market data feed can be used by Spire to populate the security database for ASX lis..."

Support for ASX Trade ITCH market data is provided by the AsxItchMarketDataFeedClient. This market data feed can be used by Spire to populate the security database for ASX listed securities, BBO quotes, time and sales, book quotes and order imbalances. In addition to real time market data, ASX Trade ITCH also provides a market data snapshot used for data recovery along with retransmission of dropped packets, both of which are fully supported.

==Configuration==

By default ASX ITCH is split into multiple feeds each handling a range of securities. Each feed is placed in its own directory and named <code>asxitch_partition[N]</code> with <code>N = 1</code> representing the first feed. Each feed also has its own configuration file structured as follows:

<pre>
---
service_locator:

# The Service Locator to authenticate with.
address: 127.0.0.1:20000

# The market data feed's username.
username: market_data_feed

# The market data feed's password.
password: 1234

# Whether to log all packets.
enable_logging: false

# The market code (MIC) to publish.
market: ASX

# Whether to synthetically publish time and sales
# based on matched orders.
is_time_and_sale: true

# Specifies how frequently to publish updates to
# the market data server.
sampling: 100ms

# The multicast group to join.
host: 233.71.185.40:21401

# The network interface to use to join
# the multicast group.
interface: 192.168.0.99:21401

# The GLIMPSE host to connect to for
# snapshot retrieval.
glimpse_host: 203.0.119.184:21801

# How long to wait for a snapshot before
# timing out.
glimpse_timeout: 5s

# The GLIMPSE username.
username: glimpse101

# The GLIMPSE password.
password: 1234
...
</pre>

==Operations==

The AsxItchMarketDataFeedClient contains the standard suite of scripts used to manage each individual feed.

The <code>start.sh</code> script is used to start either a single feed by specifying the feed's unique identifier <code>partition[N]</code> as a command line argument or used to start all feeds by passing <code>all</code> as a command line argument. Similarly the <code>stop.sh</code> script is used to stop a currently running feed. The <code>list_feeds.sh</code> will output all currently running feeds and the <code>create_softlinks.sh</code> script is used when first setting up the feeds, or when a new feed is added.

On startup a log file is created with the name <code>srv_[YYYY][MM][DD]_[HH]_[MM]_[SS].log</code> and is used to record dropped packets, any error messages or warnings, and if logging is enabled in the configuration file, a dump of every received message.

UI Kit

2020-07-14T16:43:15Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

In cases where a UI component is provided by the platform and already has an existing implementation, it may not be necessary to provide a user flow and instead the UI component can either reuse the existing user flow or defer the user flow to the platform. For example most platforms including HTML, macOS, Windows etc... already provide a text input field as well as a button, in those cases it is preferable to defer the user flow to the respective platform instead of redefining one. Only in cases where custom functionality or custom components are being created is a user flow required.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

===Ambiguities===

An ambiguity is a step that contains multiple arrows that are simultaneously satisfied. A flow chart that contains an ambiguity is ill-formed and must be resolved. For example if a step <code>Q</code> has an arrow leading into an unconditional step (such as leading into an action or signal step), it must be the only arrow leading out of <code>Q</code>, any other arrow would necessarily introduce an ambiguity. If a step has multiple arrows leading into conditional steps where more than one condition is satisfied then that too is an ambiguity. Resolving such ambiguity is done by giving each arrow a priority.

===Example: Button===

The following is an example of a simplified button user flow. The button only responds to user events when it's enabled. Furthermore whether the user presses the enter key, or the space bar, or uses the mouse to click, the button responds to all such events with the same <code>clicked</code> signal. This allows more complex UIs to respond uniformly to a button without having to explicitly specify the manner in which a user interacted with it.

Finally note that no consideration is made for a change in the label or a change in the hover state since both of those changes are strictly visual, they affect the appearance of the button but do not in anyway affect the behavior.

 
[[File:user_flow_button.png|Button example]]
 
 

===Example: Login form===

A login form's model consists of data representing a username and password that is input by the user, a state to store whether the user is in the process of logging in, and signals indicating whether the user has submitted their credentials or wishes to cancel a currently pending sign-in attempt. Its <code>model.txt</code> is hence structured as follows:
<pre>
Data:
username: The username input by the user.
password: The user's password being input.

State:
status: The sign-in status of the UI, can be one of the following values:
NONE - Default state.
SIGNING-IN - The UI is in the process of signing in.
REJECTED - The sign in was rejected, invalid username or password.
UNAVAILABLE - The server is not available.
SIGNED-IN - The sign in process succeeded.

Signals:
submit: Indicates the user has submitted their login credentials.
cancel: The user wishes to cancel the sign-in process.
</pre>

The user flow for the login form is below:

[[File:user_flow_login.png|Login example]]

File:User flow login.png

2020-07-14T00:17:28Z

Kman: Kman uploaded a new version of File:User flow login.png

UI Kit

2020-07-14T00:16:39Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

===Ambiguities===

An ambiguity is a step that contains multiple arrows that are simultaneously satisfied. A flow chart that contains an ambiguity is ill-formed and must be resolved. For example if a step <code>Q</code> has an arrow leading into an unconditional step (such as leading into an action or signal step), it must be the only arrow leading out of <code>Q</code>, any other arrow would necessarily introduce an ambiguity. If a step has multiple arrows leading into conditional steps where more than one condition is satisfied then that too is an ambiguity. Resolving such ambiguity is done by giving each arrow a priority.

===Example: Button===

The following is an example of a simplified button user flow. The button only responds to user events when it's enabled. Furthermore whether the user presses the enter key, or the space bar, or uses the mouse to click, the button responds to all such events with the same <code>clicked</code> signal. This allows more complex UIs to respond uniformly to a button without having to explicitly specify the manner in which a user interacted with it.

Finally note that no consideration is made for a change in the label or a change in the hover state since both of those changes are strictly visual, they affect the appearance of the button but do not in anyway affect the behavior.

 
[[File:user_flow_button.png|Button example]]
 
 

===Example: Login form===

A login form's model consists of data representing a username and password that is input by the user, a state to store whether the user is in the process of logging in, and signals indicating whether the user has submitted their credentials or wishes to cancel a currently pending sign-in attempt. Its <code>model.txt</code> is hence structured as follows:
<pre>
Data:
username: The username input by the user.
password: The user's password being input.

State:
status: The sign-in status of the UI, can be one of the following values:
NONE - Default state.
SIGNING-IN - The UI is in the process of signing in.
REJECTED - The sign in was rejected, invalid username or password.
UNAVAILABLE - The server is not available.
SIGNED-IN - The sign in process succeeded.

Signals:
submit: Indicates the user has submitted their login credentials.
cancel: The user wishes to cancel the sign-in process.
</pre>

The user flow for the login form is below:

[[File:user_flow_login.png|Login example]]

File:User flow login.png

2020-07-14T00:16:24Z

Kman:

UI Kit

2020-07-13T23:39:03Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

===Ambiguities===

An ambiguity is a step that contains multiple arrows that are simultaneously satisfied. A flow chart that contains an ambiguity is ill-formed and must be resolved. For example if a step <code>Q</code> has an arrow leading into an unconditional step (such as leading into an action or signal step), it must be the only arrow leading out of <code>Q</code>, any other arrow would necessarily introduce an ambiguity. If a step has multiple arrows leading into conditional steps where more than one condition is satisfied then that too is an ambiguity. Resolving such ambiguity is done by giving each arrow a priority.

===Example: Button===

The following is an example of a simplified button user flow. The button only responds to user events when it's enabled. Furthermore whether the user presses the enter key, or the space bar, or uses the mouse to click, the button responds to all such events with the same <code>clicked</code> signal. This allows more complex UIs to respond uniformly to a button without having to explicitly specify the manner in which a user interacted with it.

Finally note that no consideration is made for a change in the label or a change in the hover state since both of those changes are strictly visual, they affect the appearance of the button but do not in anyway affect the behavior.

 
[[File:user_flow_button.png|Button example]]

UI Kit

2020-07-13T23:38:44Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

===Ambiguities===

An ambiguity is a step that contains multiple arrows that are simultaneously satisfied. A flow chart that contains an ambiguity is ill-formed and must be resolved. For example if a step <code>Q</code> has an arrow leading into an unconditional step (such as leading into an action or signal step), it must be the only arrow leading out of <code>Q</code>, any other arrow would necessarily introduce an ambiguity. If a step has multiple arrows leading into conditional steps where more than one condition is satisfied then that too is an ambiguity. Resolving such ambiguity is done by giving each arrow a priority.

===Example: Button===

The following is an example of a simplified button user flow. The button only responds to user events when it's enabled. Furthermore whether the user presses the enter key, or the space bar, or uses the mouse to click, the button responds to all such events with the same <code>clicked</code> signal. This allows more complex UIs to respond uniformly to a button without having to explicitly specify the manner in which a user interacted with it.

Finally note that no consideration is made for a change in the label or a change in the hover state since both of those changes are strictly visual, they affect the appearance of the button but do not in anyway affect the behavior.

 
[[File:ui_kit_button.png|Button example]]

File:User flow button.png

2020-07-13T23:38:42Z

Kman:

UI Kit

2020-07-13T23:26:57Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

===Ambiguities===

An ambiguity is a step that contains multiple arrows that are simultaneously satisfied. A flow chart that contains an ambiguity is ill-formed and must be resolved. For example if a step <code>Q</code> has an arrow leading into an unconditional step (such as leading into an action or signal step), it must be the only arrow leading out of <code>Q</code>, any other arrow would necessarily introduce an ambiguity. If a step has multiple arrows leading into conditional steps where more than one condition is satisfied then that too is an ambiguity. Resolving such ambiguity is done by giving each arrow a priority.

UI Kit

2020-07-13T23:11:24Z

Kman:

User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how they combine to describe the complete behavior from a small component such a button to larger components such as a login window. The example that will be used in each document is a user interface for a button component.

==Model==

Fundamentally, a UI is a visual representation of a set of data in a given state. The UI takes in that data upon initialization and transforms it based on external actions either provided by the user directly or some other external agent. In order for multiple UI components to work together, individual components signal when certain changes are made to that data or to the state of the component, which allows other UI components to respond and signal changes of their own. The complete description of the data a UI component operates on, the state of the component, as well as the signals it produces form the model and is typically documented in <code>model.txt</code>. For a simple component such as a button we'd expect to see a label displayed by the button, whether the button is responding to user inputs, whether the mouse is interacting with the button, and finally a signal indicating when the user clicks on it. This would be documented as follows:

<pre>
Data:
label: The text displayed in the button.
enabled: Whether the button is responding to user actions.

State:
hovered: Whether the mouse position is within the button's visible region.

Signals:
clicked: Indicates the button was clicked by the user.
</pre>

As a general matter, fields that go under <code>Data</code> are inputs that are provided externally to the UI component, whereas fields that go under <code>State</code> are internal to the component itself. Typically a button does not know what label it should display and does not manage changes to the label, some external component shall make use of a button and provide it with a label to display. Conversely the button can independently manage whether the mouse is hovered over it on its own by keeping track of the mouse position, it needs no external agent to inform it of this state.

==User Flow==

With the model defined, the user flow describes how the model is transformed based on external events. The user flow is broken down into a set of steps represented by colored shapes and are connected to one another by arrows. In order to follow a step, a list of criteria must be met depending on type of step represented. When a step is followed a function is performed at which point the step is said to be complete and then every arrow pointing away from the step must be evaluated to determine the next step to go to. If a step has no arrows pointing out of it, then that step is said to be a terminal step at which point no further changes to the UI are possible.

Flow charts are documented using software available at https://diagrams.net

===Start===
 
[[File:ui_kit_start.png|Start step]]
 
 
Every UI component begins at the start step, it appears as a dark green circle and is typically either the left-most step of the user flow or the top-most step. It can also be formally distinguished by the fact that it's the only step that may not have any arrows pointing into it, arrows may only point away from it. The start step does not perform any function and is only used as a visual indicator to quickly determine where the flow chart begins.

If the UI performs any kind of initialization then the start step should have a single arrow pointing towards a step to handles such initialization. Refer to the login window for an example.

===Actions===
 
[[File:ui_kit_action.png|Action step]]
 
 
Actions are steps that are taken unconditionally and perform a side-effect such as changing the state of the component or updating the model. Actions can be chained together by arrows to form a sequence of side-effects or multiple actions can be consolidated into a single step that performs the sequence. The choice of chaining versus consolidating is stylistic, if a step gets to be too large then it is preferable to break it into multiple steps that are chained together. If there are multiple small actions chained together then it is preferable to consolidate.

Every side-effect specified by an action should be a single sentence that begins with a verb. For example if updating data XYZ in the model to the value 123, then the side-effect should be "Set XYZ to 123." The function of an action step is execute each side-effect in order.

A no-op can be used to indicate that no side-effect is to be performed. This can come in handy to describe an action state that does nothing but wait.

===Events===
 
[[File:ui_kit_event.png|Event step]]
 
 
An event is step external to the UI that the UI has a chance to respond to. Events can be triggered by user input such as a keyboard press, mouse movement, or other input device as well as by signals produced by other UI components, such as a button indicating that it has been clicked or an input UI indicating an update to the model. An event step is followed if the event takes place after the completion of the current step's function. While multiple events may happen very close together in time, it is never possible for multiple events to occur simultaneously.

===Conditions===
 
[[File:ui_kit_condition.png|Condition step]]
 
 
A condition is a step that is followed if at the completion of the current step's function some condition is satisfied. If a step leads to multiple conditions then it must either be the case that only one such condition can possibly be satisfied or each arrow pointing out of the step and into a condition must be labelled numerically starting from <code>0</code> in which case each condition is tested in ascending order and the first condition that is satisfied is followed. For example consider the following user flow:
 
 
[[File:ui_kit_priority.png|Prioritizing conditions]]
 
 

If the current time is 6:30 PM then all three conditions are technically satisfied and so there is an ambiguity about which condition to follow. The numeric labels on the arrows are thus used to prioritize the conditions so that the conditional step <code>current time >= 6:00 PM</code> is tested first and if satisfied then it's followed without considering the remaining conditions.

===Tests===
 
[[File:ui_kit_test.png|Test step]]
 
 

Similar to the condition step, the test step can also be used to conditionally follow an arrow. The test step itself is followed unconditionally and the function of the step is to perform a test. Once the function is completed a set of labelled arrows pointing away from the step are checked and the arrow whose label satisfies the test is followed.

Both condition steps and test steps are technically interchangeable, the choice of one or the other is stylistic. One should prefer the test step in situations where a clear question can be asked and whose answer is a single value in which case the question is written in the body of the test step and each of the possible values or value ranges is a labelled arrow.

===Signals===
 
[[File:ui_kit_signal.png|Signal step]]
 
 

The function of a signal is to inform other UI components about a change in state so that those other components can respond to such changes in the form of events. That is, a signal produced by one UI component is treated as an event by another UI component. For example, a button UI contains a <code>clicked</code> signal step indicating that the user clicked on it and in turn a form UI contains a corresponding <code>button clicked</code> event step where said form may respond by updating its data model.

Similar to an action step, signal steps are followed unconditionally.

File:Ui kit signal.png

2020-07-13T23:09:57Z

Kman:

UI Kit

2020-07-13T23:01:44Z

Kman:

UI Kit

2020-07-13T23:00:42Z

Kman:

UI Kit

2020-07-13T22:56:55Z

Kman:

File:Ui kit test.png

2020-07-13T22:56:35Z

Kman: Kman uploaded a new version of File:Ui kit test.png

File:Ui kit test.png

2020-07-13T22:55:39Z

Kman:

UI Kit

2020-07-13T22:47:17Z

Kman:

File:Ui kit priority.png

2020-07-13T22:43:55Z

Kman: Kman uploaded a new version of File:Ui kit priority.png

== Summary ==
Condition state of a user flow diagram.

File:Ui kit priority.png

2020-07-13T22:43:15Z

Kman: Condition state of a user flow diagram.

== Summary ==
Condition state of a user flow diagram.

UI Kit

2020-07-13T22:38:46Z

Kman:

File:Ui kit event.png

2020-07-13T22:32:24Z

Kman: Condition state of a user flow diagram.

== Summary ==
Condition state of a user flow diagram.

UI Kit

2020-07-13T22:22:32Z

Kman:

File:Ui kit condition.png

2020-07-13T22:11:49Z

Kman: Condition state of a user flow diagram.

== Summary ==
Condition state of a user flow diagram.

File:Ui kit action.png

2020-07-13T21:57:47Z

Kman: A user flow action state.

== Summary ==
A user flow action state.

File:Ui kit start.png

2020-07-13T21:53:59Z

Kman: Start state of a user flow diagram.

== Summary ==
Start state of a user flow diagram.

UI Kit

2020-07-13T21:36:01Z

Kman:

UI Kit

2020-07-13T21:28:23Z

Kman:

UI Kit

2020-07-13T21:28:06Z

Kman:

UI Kit

2020-07-13T21:07:50Z

Kman: Created page with "User interfaces are specified by a set of documents describing a data model, user flow, layout, and styling. This article will go over each of these documents along with how t..."

TypeScript Style Guide

2020-04-07T15:49:49Z

Kman:

This article specifies the most general guidelines used for all Spire projects written using TypeScript as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern web development practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Development Environment=

The primary operating systems supported by Spire projects are Ubuntu 18.02 LTS, Windows 10, and macOS. On all systems, nodejs is used as the build system and webpack is used as the bundler.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice, however [https://code.visualstudio.com/ Visual Studio Code] is recommended.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The name of a file should correspond to the primary class that it exports.

The default extension for TypeScript files is ''ts''

The extension used for TypeScript files containing JSX is ''tsx''

All files end with a single new line character.

=Directory Structure=

A project is broken down into a library component, a test component, and one or more application components. These components are referred to as ''artifacts''. The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''setup'' to download and install any dependencies needed to produce the artifact and the ''build'' script which produces the artifact. Typically the ''setup'' script is run only once or when a new dependency is introduced to the project, and the ''build'' script is run anytime a new build is needed.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named sudoku the following directory structure should be used:

<pre>
sudoku # Root level directory.
build.sh # Script used to build all projects on POSIX.
build.bat # Script used to build all projects on Windows.
configure.sh # Script used to configure all projects on POSIX.
configure.bat # Script used to configure all projects on Windows.
setup.sh # Script used to install all dependencies on POSIX.
setup.bat # Script used to install all dependencies on Windows.
\application # Contains source specific for the sudoku web app.
build.sh # Script used to build the web app on POSIX.
build.bat # Script used to build the web app on Windows.
configure.sh # Script used to configure the web app on POSIX.
configure.bat # Script used to configure the web app on Windows.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
setup.sh # Script used the web app dependencies on POSIX.
setup.bat # Script used the web app dependencies on Windows.
webpack.config.js # The Webpack configuration.
\source # Contains the web application source files.
\index.html # The HTML file that loads the JavaScript application.
\index.tsx # The TypeScript/JSX file containing the application.
\library # Contains the common library code.
build.sh # Script used to build the library on POSIX.
build.bat # Script used to build the library on Windows.
configure.sh # Script used to configure the library on POSIX.
configure.bat # Script used to configure the library on Windows.
package.json # The Node JS package description.
setup.sh # Script used the library on POSIX.
setup.bat # Script used the library on Windows.
tsconfig.json # The TypeScript compiler configuration.
\source # Contains the library source files.
index.ts # Exports all definitions contained in this directory.
\pages # Contains the source code for individual web pages.
index.ts # Exports all definitions for every web page defined
# in this directory.
\landing_page # Contains the source code for the landing page.
index.ts # Exports the landing page.
landing_page.tsx # The TypeScript/JSX source code for the landing page.
\page_2 # Contains the source for for another web page.
... # Structured in a similar manner as the landing page.
\resources # Contains images, fonts, CSS files and all other web
# assets.
\index.css # Contains the main CSS file, typically this is the
# only CSS file used.
\fonts # A directory of fonts used.
\tests # This directory contains tests for every page of the
# web app.
build.sh # Script used to build all tests on POSIX.
build.bat # Script used to build all tests on Windows.
configure.sh # Script used to configure all tests on POSIX.
configure.bat # Script used to configure all tests on Windows.
setup.sh # Script used to install all test dependencies on POSIX.
setup.bat # Script used to install all test dependencies on
# Windows.
\scratch # Directory containing a test/demo for a single page.
build.sh # Script used to build the test on POSIX.
build.bat # Script used to build the test on Windows.
configure.sh # Script used to configure the test on POSIX.
configure.bat # Script used to configure the test on Windows.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
setup.sh # Script used the test dependencies on POSIX.
setup.bat # Script used the test dependencies on Windows.
webpack.config.js # The Webpack configuration.
\source # Contains the test source files.
\index.html # The HTML file that loads the JavaScript application.
\index.tsx # The TypeScript/JSX file containing the application.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/sudoku

=Component Names=

Naming components can be difficult. Names are usually prefixed with the context or domain. Most components will fall under one of the following categories.

==Field==
The primary function of a field is to display data. The data can be edited. It can have a readonly property. It contains a onChange callback.

Examples: DurationField, NumberField

===Selection Field===
A specialized field. It requires a list of potential values to choose from.

Example: CountrySelectionField

==Input==
The primary function of a input is to get user input. Inputs usually do not have a initial value unlike fields. Inputs can have a readonly mode, but it is only to be used when the input should not accept input.

Example: SecurityInput

===Button===
Buttons are a specialized form of input. Only has a onClick callback.

Examples: Button, BurgerButton

==Box==
A component that displays data that cannot be directly edited.

=Syntax=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=typescript line=line>
function factorial(n: number): number {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==

Statements must end with a semi-colon ';' or a closing brace '}', even in cases where TypeScript allows them to be optional.

Lines are limited to 80 characters. Exceptions to this rule are long imports and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=typescript line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=typescript line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=typescript line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=typescript line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=typescript line=line>
// Correct.
const x = a + b;
const y = 5;

//! Incorrect
const x = a+b;
const y=5;
const z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=typescript line=line>
// Correct.
f(1, 2);
function g(a: number, b: number): number;

//! Incorrect
f(1,2);
function g(a:number,b:number);
</syntaxhighlight>

==Naming==

[https://en.wikipedia.org/wiki/Camel_case Camel case] is used for naming whereas variables and functions use mixedCase and namespaces, modules, and types use CapWords. Names should be descriptive but should avoid being verbose.

Classes and variables should be given the name of a noun and functions the name of a verb. Functions that return a boolean or boolean variables should be named in the form of a question starting with isX or hasX.

==Imports==
Imports are listed in order of most global to local. Where dependencies have the same locality, then they are ordered alphabetically. For example, the first group of dependencies to be imported are third party packages which are listed in alphabetical order based on the package name. In the above snippet the third party dependencies are jquery, react and react-router-dom which are imported in alphabetical order. Then local dependencies are imported where directories further up the hierarchy are imported first. That is, the directory '../../..' which is three levels up is imported before the directory '..' which is only one level up.

When multiple names are imported from a package, they must be listed in alphabetical order.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '../../..';
import {Model} from '..';
</syntaxhighlight>

==Declarations==

Any declaration (such as a function or class) that is intended to be imported by another file must be documented using [http://usejsdoc.org/ JSDoc style]. If the definition is local then that documentation should be omitted entirely.

Any documentation should be preceded by a blank line. In the code snippet, Properties is part of the public API so it is documented along with all of its fields, but the State is internal to the file so no aspect of it is documented.

<syntaxhighlight lang=typescript line=line>

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}
</syntaxhighlight>

==Variable Declarations==

Variables are declared so that only one variable is declared per line, prefer declaring variables using ''const'' when possible, and deferring to ''let'' otherwise, variables should always be initialized at the point of their declaration.

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=typescript line=line>
const value = (() => {
if(condition) {
return 123;
}
return 321;
})();
</syntaxhighlight>

=Example=

Below is a full example combining numerous elements of the style guide to define a typical React component. It should be used as a general reference for how code is laid out, structured, and properly spaced.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '..';
import {Model} from '.';

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}

/** Displays an HTML page. */
export class Page extends React.Component<Properties, State> {
constructor(props: Properties) {
super(props);
this.state = {
redirect: '',
isLoading: true
};
}

public componentWillMount(): void {
this.props.model.load().then(
() => {
this.setState({
isLoading: false
});
});
}

public render(): JSX.Element {
if(this.state.redirect) {
return <Router.Redirect push to={this.state.redirect}/>;
} else if(this.state.isLoading) {
return <LoadingPage/>;
}
const style = {
backgroundColor: '#FFFFFF',
font: 'Roboto 14px'
};
return (
<div style={style}>
<h1>Hello world!</h1>
<img src='cat.jpg'/>
</div>);
}
}
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials for best practices on writing portable, efficient, and clean TypeScript:

* [https://www.typescriptlang.org/docs/handbook/basic-types.html TypeScript Hand Book]

Tasks

2019-01-03T20:59:22Z

Kman: /* First Attempt */

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

<syntaxhighlight lang=python line=line>
import datetime
import time

import beam

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print('hello')
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

<syntaxhighlight lang=python line=line>
import copy
import datetime
import time

import beam

class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

# Now that we have factored out the job of repeating tasks we can rewrite our
# HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print('hello')
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

# Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Tasks

2019-01-03T20:59:10Z

Kman: /* Decomposition */

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

<syntaxhighlight lang=python line=line>
import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print('hello')
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

<syntaxhighlight lang=python line=line>
import copy
import datetime
import time

import beam

class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

# Now that we have factored out the job of repeating tasks we can rewrite our
# HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print('hello')
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

# Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Tasks

2019-01-03T20:56:14Z

Kman: /* First Attempt */

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

<syntaxhighlight lang=python line=line>
import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print('hello')
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

<syntaxhighlight lang=python line=line>
class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

Now that we have factored out the job of repeating tasks we can rewrite our HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print 'hello'
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Query

2018-12-19T18:01:04Z

Kman: /* Example */

Beam provides a series of classes to query historical and real time streaming data along a wide range of search criteria. It is one of the core APIs provided by Beam and used extensively in Spire to search through and disseminate market data and order executions.

==Structure==
Much of the data stored by Spire is in the form of a time series. The data is grouped together based on an index, for example time and sales data is indexed by its ticker symbol, order's are indexed by the account the order belongs to etc... For every item there is both a timestamp and a sequence number associated with it (to identify which data was published first in the event that two items have the same timestamp).

The most common type of query used in Spire to search through a time series is defined by the Beam::Queries::BasicQuery class. It consists of five components that are used to fully specify the type of data that is to be retrieved. Those five components are described in detail as follows:

===Index===
Every data item to query over must be associated with a single index. Specifying the value of the index to query over is defined by the class Beam::Queries::IndexedQuery.

===Range===
This component is defined by the class Beam::Queries::RangedIndex and it specifies the time range to search through as well as whether the query is strictly for historical data, real time data, or both. The class Beam::Queries::Range defines the semantics of a range and consists of a start value and an end value, both of which can be either a timestamp or a sequence number. Sequence numbers are defined by the class Beam::Queries::Sequence and it contains two special values which control the behavior of a query: LAST and PRESENT.

If the end of a range is specified to be PRESENT then the query will return all matching values that are currently stored in the database. If the end of a range is specified to be LAST or +infinity then in addition to returning all currently matching values, the query will also return matching values published in real time as they arrive.

Any other value used to mark the end of a range results in a strictly historical data query, even if the value denotes some point in the future.

===Snapshot limit===
This specifies the maximusm number of historical data items to retrieve. This is typically used to prevent a query from returning too much data. The class Beam::Queries::SnapshotLimit contains two values, the size of the limit and the type of the limit. The size controls the maximum number of historical data items are returned by a query (with the special value of UNLIMITED if every value should be returned), as well as the type of snapshot. The type dictates whether items should be returned from the beginning of the series or the end of the series (the HEAD and TAIL respectively).

For example to query for the very last item currently stored in a time series, one can use a range of [FIRST, PRESENT] and a snapshot limit whose type is TAIL and whose size is 1. Alternatively to query for the first 10 values in a time series one would use a range of [FIRST, PRESENT] and a snapshot limit with type HEAD and size 10.

The class Beam::Queries::SnapshotLimitedQuery is the component used to indicate what the snapshot limit of a query should be. By default, this class specifies that no values are to be returned (its size is 0). This is because one is expected to be explicit about how much data is desired. The special value Beam::Queries::SnapshotLimit::Unlimited() can be used to explicitly indicate that there is no limit on how much data should be returned, however, it should be noted that the database engine handling the request may impose limits of its own regarding the maximum size of a snapshot.

===Interruption policy===
When querying for real time data it is possible for the query to get interrupted, usually due to a disconnection. This component, defined by Beam::Queries::InterruptableQuery, specifies what action should be taken in the event of such an interruption. The possible recovery options are defined by the enumerator Beam::Queries::InterruptionPolicy as follows:

RECOVER_DATA, the query should attempt to re-establish a connection to the database and recover any data that was published during the time that the query was interrupted.
IGNORE_CONTINUE, the query should attempt to re-establish a connection to the database but ignore any data that was published during the time that the query was interrupted. This is usually desirable when only live, real time data is desired as this option will omit any stale data published during the interruption.
BREAK_QUERY, the query should abort, indicating an exception. This is the default interruption policy.

===Filter===

==Example==
An example of a query for historical data might be to retrieve the first 1000 time and sales for MSFT.NSDQ from December 11th, 2018 to December 12th, 2018.

===C++===
<syntaxhighlight lang=c++ line=line>
#include <iostream>
#include "Nexus/MarketDataService/SecurityMarketDataQuery.hpp"
#include "Nexus/ServiceClients/ApplicationServiceClients.hpp"

int main() {
auto socketThreadPool = Beam::Network::SocketThreadPool();
auto timerThreadPool = Beam::Threading::TimerThreadPool();

// Connect to the service.
auto serviceClients = Nexus::ApplicationServiceClients(
Beam::Network::IpAddress("127.0.0.1", 20000), "username",
"password", Beam::Ref(socketThreadPool), Beam::Ref(timerThreadPool));
serviceClients.Open();
auto& marketDataClient = serviceClients.GetMarketDataClient();

// Build the query.
auto query = Nexus::MarketDataService::SecurityMarketDataQuery();
query.SetIndex(Nexus::ParseSecurity("MSFT.NSDQ"));
query.SetRange(Beam::TimeService::ToUtcTime(
boost::posix_time::ptime(boost::gregorian::date(2018, 12, 11))),
Beam::TimeService::ToUtcTime(
boost::posix_time::ptime(boost::gregorian::date(2018, 12, 12))));
query.SetSnapshotLimit(Beam::Queries::SnapshotLimit::Type::HEAD, 1000);

// Build the Queue to store the results.
auto queue = std::make_shared<Beam::Queue<Nexus::TimeAndSale>>();

// Submit the query to the market data service.
marketDataClient.QueryTimeAndSales(query, queue);

// Print the results
try {
while(true) {
std::cout << queue->Top().m_price << std::endl;
queue->Pop();
}
} catch(const Beam::PipeBrokenException&) {}
}
</syntaxhighlight>

===Python===
<syntaxhighlight lang=python line=line>
import beam
import nexus
import datetime

# Connect to the service.
service_clients = nexus.ApplicationServiceClients(
beam.network.IpAddress('127.0.0.1', 20000),
'username', 'password')

service_clients.open()
market_data_client = service_clients.get_market_data_client()

# Build the query.
query = beam.queries.Query()
query.index = nexus.parse_security('MSFT.NSDQ')
query.range = beam.queries.Range(beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 11)), beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 12)))
query.snapshot_limit = beam.queries.SnapshotLimit(
beam.queries.SnapshotLimit.Type.HEAD, 1000)

# Build the Queue to store the results.
queue = beam.Queue()

# Submit the query to the market data service.
market_data_client.query_time_and_sales(query, queue)

# Print the results
try:
while True:
print(queue.top().price)
queue.pop()
except:
pass
</syntaxhighlight>

Query

2018-12-19T17:59:56Z

Kman: /* C++ */

Beam provides a series of classes to query historical and real time streaming data along a wide range of search criteria. It is one of the core APIs provided by Beam and used extensively in Spire to search through and disseminate market data and order executions.

==Structure==
Much of the data stored by Spire is in the form of a time series. The data is grouped together based on an index, for example time and sales data is indexed by its ticker symbol, order's are indexed by the account the order belongs to etc... For every item there is both a timestamp and a sequence number associated with it (to identify which data was published first in the event that two items have the same timestamp).

The most common type of query used in Spire to search through a time series is defined by the Beam::Queries::BasicQuery class. It consists of five components that are used to fully specify the type of data that is to be retrieved. Those five components are described in detail as follows:

===Index===
Every data item to query over must be associated with a single index. Specifying the value of the index to query over is defined by the class Beam::Queries::IndexedQuery.

===Range===
This component is defined by the class Beam::Queries::RangedIndex and it specifies the time range to search through as well as whether the query is strictly for historical data, real time data, or both. The class Beam::Queries::Range defines the semantics of a range and consists of a start value and an end value, both of which can be either a timestamp or a sequence number. Sequence numbers are defined by the class Beam::Queries::Sequence and it contains two special values which control the behavior of a query: LAST and PRESENT.

If the end of a range is specified to be PRESENT then the query will return all matching values that are currently stored in the database. If the end of a range is specified to be LAST or +infinity then in addition to returning all currently matching values, the query will also return matching values published in real time as they arrive.

Any other value used to mark the end of a range results in a strictly historical data query, even if the value denotes some point in the future.

===Snapshot limit===
This specifies the maximusm number of historical data items to retrieve. This is typically used to prevent a query from returning too much data. The class Beam::Queries::SnapshotLimit contains two values, the size of the limit and the type of the limit. The size controls the maximum number of historical data items are returned by a query (with the special value of UNLIMITED if every value should be returned), as well as the type of snapshot. The type dictates whether items should be returned from the beginning of the series or the end of the series (the HEAD and TAIL respectively).

For example to query for the very last item currently stored in a time series, one can use a range of [FIRST, PRESENT] and a snapshot limit whose type is TAIL and whose size is 1. Alternatively to query for the first 10 values in a time series one would use a range of [FIRST, PRESENT] and a snapshot limit with type HEAD and size 10.

The class Beam::Queries::SnapshotLimitedQuery is the component used to indicate what the snapshot limit of a query should be. By default, this class specifies that no values are to be returned (its size is 0). This is because one is expected to be explicit about how much data is desired. The special value Beam::Queries::SnapshotLimit::Unlimited() can be used to explicitly indicate that there is no limit on how much data should be returned, however, it should be noted that the database engine handling the request may impose limits of its own regarding the maximum size of a snapshot.

===Interruption policy===
When querying for real time data it is possible for the query to get interrupted, usually due to a disconnection. This component, defined by Beam::Queries::InterruptableQuery, specifies what action should be taken in the event of such an interruption. The possible recovery options are defined by the enumerator Beam::Queries::InterruptionPolicy as follows:

RECOVER_DATA, the query should attempt to re-establish a connection to the database and recover any data that was published during the time that the query was interrupted.
IGNORE_CONTINUE, the query should attempt to re-establish a connection to the database but ignore any data that was published during the time that the query was interrupted. This is usually desirable when only live, real time data is desired as this option will omit any stale data published during the interruption.
BREAK_QUERY, the query should abort, indicating an exception. This is the default interruption policy.

===Filter===

==Example==
An example of a query for historical data might be to retrieve the first 1000 time and sales for MSFT.NSDQ from August 11th, 2016 to August 12th, 2016.

===C++===
<syntaxhighlight lang=c++ line=line>
#include <iostream>
#include "Nexus/MarketDataService/SecurityMarketDataQuery.hpp"
#include "Nexus/ServiceClients/ApplicationServiceClients.hpp"

int main() {
auto socketThreadPool = Beam::Network::SocketThreadPool();
auto timerThreadPool = Beam::Threading::TimerThreadPool();

// Connect to the service.
auto serviceClients = Nexus::ApplicationServiceClients(
Beam::Network::IpAddress("127.0.0.1", 20000), "username",
"password", Beam::Ref(socketThreadPool), Beam::Ref(timerThreadPool));
serviceClients.Open();
auto& marketDataClient = serviceClients.GetMarketDataClient();

// Build the query.
auto query = Nexus::MarketDataService::SecurityMarketDataQuery();
query.SetIndex(Nexus::ParseSecurity("MSFT.NSDQ"));
query.SetRange(Beam::TimeService::ToUtcTime(
boost::posix_time::ptime(boost::gregorian::date(2018, 12, 11))),
Beam::TimeService::ToUtcTime(
boost::posix_time::ptime(boost::gregorian::date(2018, 12, 12))));
query.SetSnapshotLimit(Beam::Queries::SnapshotLimit::Type::HEAD, 1000);

// Build the Queue to store the results.
auto queue = std::make_shared<Beam::Queue<Nexus::TimeAndSale>>();

// Submit the query to the market data service.
marketDataClient.QueryTimeAndSales(query, queue);

// Print the results
try {
while(true) {
std::cout << queue->Top().m_price << std::endl;
queue->Pop();
}
} catch(const Beam::PipeBrokenException&) {}
}
</syntaxhighlight>

===Python===
<syntaxhighlight lang=python line=line>
import beam
import nexus
import datetime

# Connect to the service.
service_clients = nexus.ApplicationServiceClients(
beam.network.IpAddress('127.0.0.1', 20000),
'username', 'password')

service_clients.open()
market_data_client = service_clients.get_market_data_client()

# Build the query.
query = beam.queries.Query()
query.index = nexus.parse_security('MSFT.NSDQ')
query.range = beam.queries.Range(beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 11)), beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 12)))
query.snapshot_limit = beam.queries.SnapshotLimit(
beam.queries.SnapshotLimit.Type.HEAD, 1000)

# Build the Queue to store the results.
queue = beam.Queue()

# Submit the query to the market data service.
market_data_client.query_time_and_sales(query, queue)

# Print the results
try:
while True:
print(queue.top().price)
queue.pop()
except:
pass
</syntaxhighlight>

Query

2018-12-19T16:53:08Z

Kman: /* Python */

Beam provides a series of classes to query historical and real time streaming data along a wide range of search criteria. It is one of the core APIs provided by Beam and used extensively in Spire to search through and disseminate market data and order executions.

==Structure==
Much of the data stored by Spire is in the form of a time series. The data is grouped together based on an index, for example time and sales data is indexed by its ticker symbol, order's are indexed by the account the order belongs to etc... For every item there is both a timestamp and a sequence number associated with it (to identify which data was published first in the event that two items have the same timestamp).

The most common type of query used in Spire to search through a time series is defined by the Beam::Queries::BasicQuery class. It consists of five components that are used to fully specify the type of data that is to be retrieved. Those five components are described in detail as follows:

===Index===
Every data item to query over must be associated with a single index. Specifying the value of the index to query over is defined by the class Beam::Queries::IndexedQuery.

===Range===
This component is defined by the class Beam::Queries::RangedIndex and it specifies the time range to search through as well as whether the query is strictly for historical data, real time data, or both. The class Beam::Queries::Range defines the semantics of a range and consists of a start value and an end value, both of which can be either a timestamp or a sequence number. Sequence numbers are defined by the class Beam::Queries::Sequence and it contains two special values which control the behavior of a query: LAST and PRESENT.

If the end of a range is specified to be PRESENT then the query will return all matching values that are currently stored in the database. If the end of a range is specified to be LAST or +infinity then in addition to returning all currently matching values, the query will also return matching values published in real time as they arrive.

Any other value used to mark the end of a range results in a strictly historical data query, even if the value denotes some point in the future.

===Snapshot limit===
This specifies the maximusm number of historical data items to retrieve. This is typically used to prevent a query from returning too much data. The class Beam::Queries::SnapshotLimit contains two values, the size of the limit and the type of the limit. The size controls the maximum number of historical data items are returned by a query (with the special value of UNLIMITED if every value should be returned), as well as the type of snapshot. The type dictates whether items should be returned from the beginning of the series or the end of the series (the HEAD and TAIL respectively).

For example to query for the very last item currently stored in a time series, one can use a range of [FIRST, PRESENT] and a snapshot limit whose type is TAIL and whose size is 1. Alternatively to query for the first 10 values in a time series one would use a range of [FIRST, PRESENT] and a snapshot limit with type HEAD and size 10.

The class Beam::Queries::SnapshotLimitedQuery is the component used to indicate what the snapshot limit of a query should be. By default, this class specifies that no values are to be returned (its size is 0). This is because one is expected to be explicit about how much data is desired. The special value Beam::Queries::SnapshotLimit::Unlimited() can be used to explicitly indicate that there is no limit on how much data should be returned, however, it should be noted that the database engine handling the request may impose limits of its own regarding the maximum size of a snapshot.

===Interruption policy===
When querying for real time data it is possible for the query to get interrupted, usually due to a disconnection. This component, defined by Beam::Queries::InterruptableQuery, specifies what action should be taken in the event of such an interruption. The possible recovery options are defined by the enumerator Beam::Queries::InterruptionPolicy as follows:

RECOVER_DATA, the query should attempt to re-establish a connection to the database and recover any data that was published during the time that the query was interrupted.
IGNORE_CONTINUE, the query should attempt to re-establish a connection to the database but ignore any data that was published during the time that the query was interrupted. This is usually desirable when only live, real time data is desired as this option will omit any stale data published during the interruption.
BREAK_QUERY, the query should abort, indicating an exception. This is the default interruption policy.

===Filter===

==Example==
An example of a query for historical data might be to retrieve the first 1000 time and sales for MSFT.NSDQ from August 11th, 2016 to August 12th, 2016.

===C++===
<syntaxhighlight lang=c++ line=line>
#include <iostream>
#include "Nexus/MarketDataService/SecurityMarketDataQuery.hpp"
#include "Nexus/ServiceClients/ApplicationServiceClients.hpp"

int main() {
Beam::Network::SocketThreadPool socketThreadPool;
Beam::Threading::TimerThreadPool timerThreadPool;

// Connect to the service.
Nexus::ApplicationServiceClients serviceClients{
Beam::Network::IpAddress{"127.0.0.1", 20000}, "username",
"password", Beam::Ref(socketThreadPool), Beam::Ref(timerThreadPool)};
serviceClients.Open();
auto& marketDataClient = serviceClients.GetMarketDataClient();

// Build the query.
auto query = Nexus::MarketDataService::SecurityMarketDataQuery();
query.SetIndex(Nexus::ParseSecurity("MSFT.NSDQ"));
query.SetRange(Beam::TimeService::ToUtcTime(
boost::posix_time::ptime{boost::gregorian::date{2016 , 8, 11}}),
Beam::TimeService::ToUtcTime(
boost::posix_time::ptime{boost::gregorian::date{2016, 8, 12}}));
query.SetSnapshotLimit(Beam::Queries::SnapshotLimit::Type::HEAD, 1000);

// Build the Queue to store the results.
auto queue = std::make_shared<Beam::Queue<Nexus::TimeAndSale>>();

// Submit the query to the market data service.
marketDataClient.QueryTimeAndSales(query, queue);

// Print the results
try {
while(true) {
std::cout << queue->Top().m_price << std::endl;
queue->Pop();
}
} catch(const Beam::PipeBrokenException&) {}
}
</syntaxhighlight>

===Python===
<syntaxhighlight lang=python line=line>
import beam
import nexus
import datetime

# Connect to the service.
service_clients = nexus.ApplicationServiceClients(
beam.network.IpAddress('127.0.0.1', 20000),
'username', 'password')

service_clients.open()
market_data_client = service_clients.get_market_data_client()

# Build the query.
query = beam.queries.Query()
query.index = nexus.parse_security('MSFT.NSDQ')
query.range = beam.queries.Range(beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 11)), beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 12)))
query.snapshot_limit = beam.queries.SnapshotLimit(
beam.queries.SnapshotLimit.Type.HEAD, 1000)

# Build the Queue to store the results.
queue = beam.Queue()

# Submit the query to the market data service.
market_data_client.query_time_and_sales(query, queue)

# Print the results
try:
while True:
print(queue.top().price)
queue.pop()
except:
pass
</syntaxhighlight>

Query

2018-12-19T16:52:25Z

Kman: /* Python */

Beam provides a series of classes to query historical and real time streaming data along a wide range of search criteria. It is one of the core APIs provided by Beam and used extensively in Spire to search through and disseminate market data and order executions.

==Structure==
Much of the data stored by Spire is in the form of a time series. The data is grouped together based on an index, for example time and sales data is indexed by its ticker symbol, order's are indexed by the account the order belongs to etc... For every item there is both a timestamp and a sequence number associated with it (to identify which data was published first in the event that two items have the same timestamp).

The most common type of query used in Spire to search through a time series is defined by the Beam::Queries::BasicQuery class. It consists of five components that are used to fully specify the type of data that is to be retrieved. Those five components are described in detail as follows:

===Index===
Every data item to query over must be associated with a single index. Specifying the value of the index to query over is defined by the class Beam::Queries::IndexedQuery.

===Range===
This component is defined by the class Beam::Queries::RangedIndex and it specifies the time range to search through as well as whether the query is strictly for historical data, real time data, or both. The class Beam::Queries::Range defines the semantics of a range and consists of a start value and an end value, both of which can be either a timestamp or a sequence number. Sequence numbers are defined by the class Beam::Queries::Sequence and it contains two special values which control the behavior of a query: LAST and PRESENT.

If the end of a range is specified to be PRESENT then the query will return all matching values that are currently stored in the database. If the end of a range is specified to be LAST or +infinity then in addition to returning all currently matching values, the query will also return matching values published in real time as they arrive.

Any other value used to mark the end of a range results in a strictly historical data query, even if the value denotes some point in the future.

===Snapshot limit===
This specifies the maximusm number of historical data items to retrieve. This is typically used to prevent a query from returning too much data. The class Beam::Queries::SnapshotLimit contains two values, the size of the limit and the type of the limit. The size controls the maximum number of historical data items are returned by a query (with the special value of UNLIMITED if every value should be returned), as well as the type of snapshot. The type dictates whether items should be returned from the beginning of the series or the end of the series (the HEAD and TAIL respectively).

For example to query for the very last item currently stored in a time series, one can use a range of [FIRST, PRESENT] and a snapshot limit whose type is TAIL and whose size is 1. Alternatively to query for the first 10 values in a time series one would use a range of [FIRST, PRESENT] and a snapshot limit with type HEAD and size 10.

The class Beam::Queries::SnapshotLimitedQuery is the component used to indicate what the snapshot limit of a query should be. By default, this class specifies that no values are to be returned (its size is 0). This is because one is expected to be explicit about how much data is desired. The special value Beam::Queries::SnapshotLimit::Unlimited() can be used to explicitly indicate that there is no limit on how much data should be returned, however, it should be noted that the database engine handling the request may impose limits of its own regarding the maximum size of a snapshot.

===Interruption policy===
When querying for real time data it is possible for the query to get interrupted, usually due to a disconnection. This component, defined by Beam::Queries::InterruptableQuery, specifies what action should be taken in the event of such an interruption. The possible recovery options are defined by the enumerator Beam::Queries::InterruptionPolicy as follows:

RECOVER_DATA, the query should attempt to re-establish a connection to the database and recover any data that was published during the time that the query was interrupted.
IGNORE_CONTINUE, the query should attempt to re-establish a connection to the database but ignore any data that was published during the time that the query was interrupted. This is usually desirable when only live, real time data is desired as this option will omit any stale data published during the interruption.
BREAK_QUERY, the query should abort, indicating an exception. This is the default interruption policy.

===Filter===

==Example==
An example of a query for historical data might be to retrieve the first 1000 time and sales for MSFT.NSDQ from August 11th, 2016 to August 12th, 2016.

===C++===
<syntaxhighlight lang=c++ line=line>
#include <iostream>
#include "Nexus/MarketDataService/SecurityMarketDataQuery.hpp"
#include "Nexus/ServiceClients/ApplicationServiceClients.hpp"

int main() {
Beam::Network::SocketThreadPool socketThreadPool;
Beam::Threading::TimerThreadPool timerThreadPool;

// Connect to the service.
Nexus::ApplicationServiceClients serviceClients{
Beam::Network::IpAddress{"127.0.0.1", 20000}, "username",
"password", Beam::Ref(socketThreadPool), Beam::Ref(timerThreadPool)};
serviceClients.Open();
auto& marketDataClient = serviceClients.GetMarketDataClient();

// Build the query.
auto query = Nexus::MarketDataService::SecurityMarketDataQuery();
query.SetIndex(Nexus::ParseSecurity("MSFT.NSDQ"));
query.SetRange(Beam::TimeService::ToUtcTime(
boost::posix_time::ptime{boost::gregorian::date{2016 , 8, 11}}),
Beam::TimeService::ToUtcTime(
boost::posix_time::ptime{boost::gregorian::date{2016, 8, 12}}));
query.SetSnapshotLimit(Beam::Queries::SnapshotLimit::Type::HEAD, 1000);

// Build the Queue to store the results.
auto queue = std::make_shared<Beam::Queue<Nexus::TimeAndSale>>();

// Submit the query to the market data service.
marketDataClient.QueryTimeAndSales(query, queue);

// Print the results
try {
while(true) {
std::cout << queue->Top().m_price << std::endl;
queue->Pop();
}
} catch(const Beam::PipeBrokenException&) {}
}
</syntaxhighlight>

===Python===
<syntaxhighlight lang=python line=line>
import beam
import nexus
import datetime

# Connect to the service.
service_clients = nexus.ApplicationServiceClients(
beam.network.IpAddress('127.0.0.1', 20000),
'username', 'password')

service_clients.open()
market_data_client = service_clients.get_market_data_client()

# Build the query.
query = beam.queries.Query()
query.index = nexus.parse_security('MSFT.NSDQ')
query.range = beam.queries.Range(beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 11)), beam.time_service.to_utc_time(
datetime.datetime(2018, 12, 12)))
query.snapshot_limit = beam.queries.SnapshotLimit(
beam.queries.SnapshotLimit.Type.HEAD, 1000)

# Build the Queue to store the results.
queue = beam.Queue()

# Submit the query to the market data service.
market_data_client.query_time_and_sales(query, queue)

# Print the results
try:
while True:
print queue.top().price
queue.pop()
except:
pass
</syntaxhighlight>

Tasks

2018-09-11T21:03:32Z

Kman: /* Decomposition */

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

<syntaxhighlight lang=python line=line>
import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print 'hello'
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

<syntaxhighlight lang=python line=line>
class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

Now that we have factored out the job of repeating tasks we can rewrite our HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print 'hello'
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Tasks

2018-09-11T21:02:50Z

Kman: /* First Attempt */

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

<syntaxhighlight lang=python line=line>
import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print 'hello'
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()
</syntaxhighlight>

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

Now that we have factored out the job of repeating tasks we can rewrite our HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print 'hello'
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Tasks

2018-09-11T20:57:52Z

Kman:

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.

=Interface=
==Task==

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:

{| class="wikitable"
|-
! scope="col"| State
! scope="col"| Description
|-
| scope="row"| NONE
| The task has not yet been executed.
|-
| scope="row"| INITIALIZING
| The task is performing some initialization, during this state no sub-tasks may be executed.
|-
| scope="row"| ACTIVE
| The task is running, during this state sub-tasks may be executed.
|-
| scope="row"| PENDING_CANCEL
| A request to cancel the task has been made, no new sub-tasks may be executed.
|-
| scope="row"| CANCELED
| The task was canceled.
|-
| scope="row"| FAILED
| The task could not complete due to an error.
|-
| scope="row"| EXPIRED
| The task could not complete due to a time constraint.
|-
| scope="row"| COMPLETE
| The task completed successfully.
|}

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:

{| class="wikitable"
|-
! scope="col"| Name
! scope="col"| Type
! scope="col"| Description
|-
| scope="row"| m_state
| Beam::Tasks::Task::State
| The state of the task.
|-
| scope="row"| m_message
| std::string
| A message describing the reason for the transition.
|}

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.

==Task Factory==

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.

===Continuations===

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.

==BasicTask==

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.

=Example=

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.

==First Attempt==

import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print 'hello'
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()

==Decomposition==

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

Now that we have factored out the job of repeating tasks we can rewrite our HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print 'hello'
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

Tasks

2018-09-11T20:14:56Z

Kman: Created page with "Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a se..."

Tasks provide a way of encapsulating and managing asynchronous actions in a composable manner. They are primarily used to perform some sort of I/O operation and/or manage a series of sub-tasks. Beam provides several classes to define your own tasks as well as classes that connect tasks to one another.

The task API in Beam is defined by two base classes, the class Beam::Tasks::Task which represents a task, and the class Beam::Tasks::TaskFactory which constructs tasks. In this article we will explore how we can use these two classes in ways that allow us to start, stop, modify and resume asynchronous actions.
Contents

1 Interface
1.1 Task
1.2 Task Factory
1.2.1 Continuations
1.3 BasicTask
2 Example
2.1 First Attempt
2.2 Decomposition

Interface[edit]
Task[edit]

The Task class defines two methods, an Execute() method to start the task and a Cancel() method to request that the task stop. Both operations are asynchronous, meaning that they return immediately and the actual operation of the task takes place in a separate thread of execution. In order to keep track of the progress of a task one must monitor its state which can be any of the following:
State Description
NONE The task has not yet been executed.
INITIALIZING The task is performing some initialization, during this state no sub-tasks may be executed.
ACTIVE The task is running, during this state sub-tasks may be executed.
PENDING_CANCEL A request to cancel the task has been made, no new sub-tasks may be executed.
CANCELED The task was canceled.
FAILED The task could not complete due to an error.
EXPIRED The task could not complete due to a time constraint.
COMPLETE The task completed successfully.

The states CANCELED, FAILED, EXPIRED and COMPLETE all represent terminal states. Before a task can transition to a terminal state, all of its sub tasks must be in a terminal state. Furthermore once a task is in a terminal state the task is not permitted to perform any additional action or transition to a different state.

The current state of the task along with all of its transitions is accessed through its Publisher by calling the GetPublisher() method. The publisher will emit objects of type Beam::Tasks::Task::StateEntry which contains two fields as follows:
Name Type Description
m_state Beam::Tasks::Task::State The state of the task.
m_message std::string A message describing the reason for the transition.

In effect a task begins in the NONE state, is then started via the Execute() method, transitions into the INITIALIZATION state where it performs any setup needed, then proceeds to the ACTIVE state where it performs its operation including executing any required sub-tasks, and then finally terminates all of its sub-tasks and performs any final clean-up before ending in a terminal state. During any point after the INITIALIZATION state it may encounter a cancel request (via the Cancel() method) or an error, either of which should result in cleaning-up and terminating its sub-tasks before transitioning to the FAILED or CANCELED state.
Task Factory[edit]

The task factory is responsible for creating new tasks by invoking its Create() method. In addition to this a task factory also keeps track of the parameters and state needed to create tasks. Setting a task's parameter is done by calling the factory's Set(name, value) method and retrieving a parameter is done via the Get(name) method.
Continuations[edit]

One additional operation that task factories perform is constructing what is called a continuation task. Continuations are a mechanism that allow us to resume a task that previously terminated, but more than that they also allow us to modify the parameters of that task. In a sense, a continuation lets us take a terminated task, modify it, and then continue running it with those modifications.

To do this, task factories have a method PrepareContinuation(task). To use it you pass into it a task that has terminated, then you modify its properties using the Set(name, value) method, and then finally you invoke the Create() method to get a newly constructed task that represents the continuation of the old task.

Not all tasks support continuations, those that do not will throw a Beam::NotSupportedException.
BasicTask[edit]

As a great deal of care must be taken to ensure that tasks properly transition from State to State, including managing sub-tasks, handling cancel requests etc... Beam provides the Beam::Tasks::BasicTask as a base class which can be inherited from to take care of much of the work needed to write a proper task. For example it ensures that upon a cancel request that the task transitions into the PENDING_CANCEL state and terminates all managed sub-tasks.

To make use of a the BasicTask you need only implement the OnExecute() method to start your task, and the OnCancel() method to handle cancelling your class.
Example[edit]

To showcase a simple example, let's build a task that prints "hello" every second a given number of times. We will write a HelloTask class which inherits from BasicTask, and a HelloTaskFactory.
First Attempt[edit]

import beam
import datetime
import time

class HelloTask(beam.tasks.BasicTask):
'''Prints hello a specified number of times.'''

def __init__(self, timer, iterations):
''' Constructs this task.
:param timer: The Timer used to wait between successive prints.
:param iterations: The number of times to print.
'''

# We must make sure to initialize the base class.
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.iterations = iterations

# The number of times we've printed so far.
self.counter = 0

# Used to handle timer callbacks.
self.tasks = beam.RoutineTaskQueue()

# This overrides BasicTask.on_execute.
# When called we can assume that our Task is in the INITIALIZATION state.
def on_execute(self):

# To initialize our task we will monitor our timer and then start the timer.
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()

# Once the initialization is complete we transition to the ACTIVE state.
self.set_active()

# This overrides BasicTask.on_cancel.
# When called we can assume that our Task is in the PENDING_CANCEL state.
# No new sub-tasks may be executed.
def on_cancel(self):

# In order to synchronize handling the cancel operation with the timer,
# we will push a helper function onto our RoutineTaskQueue.
# This ensures no race-conditions take place between the timer and
# the cancel request.
self.tasks.push(self._on_cancel)

# This handles the timer expiry.
def on_timer(self, result):
if result == beam.threading.Timer.Result.EXPIRED:

# This branch implies that our timer expired normally.
print 'hello'
self.counter += 1
if self.counter >= self.iterations:

# There is nothing more to print, so transition to
# a terminal state, which by default is the COMPLETE state.
self.set_terminal()
else:

# There are still further iterations, restart the timer.
self.timer.start()
else:

# This branch implies that we canceled the timer in response
# to a cancel request.
# In this case we set our state to CANCELED.
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
if self.counter < self.iterations:

# Only cancel the timer if there are iterations remaining.
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
'''Builds HelloTasks.'''

# Typically the parameters that get passed into the Task are
# defined as static constant strings in the TaskFactory.
# This makes it easier to identify the properties of a task
# as well as reference them (avoiding potential typos).
ITERATIONS = 'iterations'

def __init__(self, timer_factory):
'''Constructs a HelloTaskFactory.
:param timer_factory: Used to construct Timers.
'''

# Factories will typically inherit from TaskFactory as a base class.
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

# The constructor should define all the properties and default
# values for those properties.
self.define_property(HelloTaskFactory.ITERATIONS, 10)

# This variable keeps track of continuations.
self.continuation_task = None

# This overrides the TaskFactory create method.
def create(self):

if self.continuation_task is None:

# We are not creating a continuation task, so all we need to do is
# construct a HelloTask using the ITERATIONS property defined above.
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS))
else:

# We are creating a continuation task. The continuation of a HelloTask of
# N iterations that has already printed C times is basically a HelloTask
# that prints N - C times.
continuation = HelloTask(
self.timer_factory(datetime.timedelta(seconds = 1)),
self.get(HelloTaskFactory.ITERATIONS) - self.continuation_task.counter)
self.continuation_task = None
return continuation

# This overrides the TaskFactory prepare_continuation method.
def prepare_continuation(self, task):

# We store the task to continue.
self.continuation_task = task

def main():

# Construct the HelloTaskFactory using the LiveTimer for 5 iterations.
factory = HelloTaskFactory(beam.threading.LiveTimer)
factory.set(HelloTaskFactory.ITERATIONS, 5)
task = factory.create()
task.execute()

# Let's sleep for 2 seconds before canceling the task.
# It should print hello twice.
time.sleep(2)
task.cancel()

# Wait for the task to enter the CANCELED state.
beam.tasks.wait(task)

# Build the continuation task and execute it. To do this we first
# call prepare_continuation, then we make our modifications using the set
# method, then we create the task and execute it.
factory.prepare_continuation(task)
factory.set(HelloTaskFactory.ITERATIONS, 7)
task = factory.create()

# We expect it to print hello three times before coming to an end.
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()

Decomposition[edit]

The above example works, but upon reflection we should notice that this Task is responsible for two distinct things. One is the responsibility of printing, and the other is the responsibility of repeating. Given that the purpose of tasks is to be able to compose asynchronous operations we should separate these two responsibilities from one another. To do that we will change our HelloTask so that all it does is print hello after a specified time period, followed by a RepetitionTask which repeats a task a specified number of times. The benefit of this is that our RepetitionTask can be reused to repeat any task whatsoever down the road.

We will define it as follows:

class RepetitionTask(beam.tasks.BasicTask):
'''Repeats a Task a specified number of times.'''

def __init__(self, task_factory, iterations):
'''Constructs the Task.
:param task_factory: Builds the Task to repeat.
:param iterations: The number of times to repeat the Task.
'''
beam.tasks.BasicTask.__init__(self)

# We should always make a deep copy of factories in order to
# avoid modifying a factory belonging to another task or having
# another task modify our factory.
self.task_factory = copy.deepcopy(task_factory)
self.iterations = iterations
self.counter = 0

# This stores the task currently being executed.
self.task = None

# This is used to handle callbacks from our tasks.
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):

# Defer to a helper function.
self.execute_task()

def on_cancel(self):

# As before, to avoid race conditions between cancels and
# our task we will push a callback onto a RoutineTaskQueue
# to handle cancellations.
self.tasks.push(self._on_cancel)

def on_state(self, state_entry):

# This method handles transitions of the task we're repeating.
if state_entry.state == beam.tasks.Task.State.CANCELED:

# This branch indicates that we canceled our task which
# means that we're handling a cancel request.
self.set_terminal(beam.tasks.Task.State.CANCELED)
elif beam.tasks.is_terminal(state_entry.state):

# This branch indicates that our task terminated and
# hence we should repeat.
self.execute_task()

def _on_cancel(self):
if self.counter < self.iterations:

# Similar to before, only cancel if we still have
# repetitions to process.
self.task.cancel()

def execute_task(self):
if self.counter >= self.iterations:

# This branch indicates there are no more iterations left.
self.set_terminal()
else:

# This branch indicates that we need to repeat the task
# by constructing a new one and executing it.
self.counter += 1
self.task = self.task_factory.create()
self.task.get_publisher().monitor(self.tasks.get_slot(self.on_state))
self.task.execute()

# This class is very similar to the HelloTaskFactory.
class RepetitionTaskFactory(beam.tasks.TaskFactory):
ITERATIONS = 'iterations'

def __init__(self, task_factory):
beam.tasks.TaskFactory.__init__(self)
self.task_factory = copy.deepcopy(task_factory)
self.define_property(RepetitionTaskFactory.ITERATIONS, 10)
self.continuation_task = None

def create(self):
if self.continuation_task is None:
return RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS))
else:
continuation = RepetitionTask(self.task_factory,
self.get(RepetitionTaskFactory.ITERATIONS) -
self.continuation_task.counter)
self.continuation_task = None
return continuation

def prepare_continuation(self, task):
self.continuation_task = task

Now that we have factored out the job of repeating tasks we can rewrite our HelloTask as follows:

class HelloTask(beam.tasks.BasicTask):
def __init__(self, timer):
beam.tasks.BasicTask.__init__(self)
self.timer = timer
self.tasks = beam.RoutineTaskQueue()

def on_execute(self):
self.timer.get_publisher().monitor(self.tasks.get_slot(self.on_timer))
self.timer.start()
self.set_active()

def on_cancel(self):
self.tasks.push(self._on_cancel)

def on_timer(self, result):
print 'hello'
if result == beam.threading.Timer.Result.EXPIRED:
self.set_terminal()
else:
self.set_terminal(beam.tasks.Task.State.CANCELED)

def _on_cancel(self):
self.timer.cancel()

class HelloTaskFactory(beam.tasks.TaskFactory):
def __init__(self, timer_factory):
beam.tasks.TaskFactory.__init__(self)
self.timer_factory = timer_factory

def create(self):
return HelloTask(self.timer_factory(datetime.timedelta(seconds = 1)))

Finally once these two pieces are in place we can combine them as follows:

def main():

# First build the HelloTaskFactory
hello_factory = HelloTaskFactory(beam.threading.LiveTimer)

# Pass the above factory into the RepetitionTaskFactory.
# The result is a factory that composes a RepetitionTask with
# a HelloTask.
factory = RepetitionTaskFactory(hello_factory)
factory.set(RepetitionTaskFactory.ITERATIONS, 5)

# Now we can use the factory similarly to how we used it before.
task = factory.create()
task.execute()
time.sleep(2)
task.cancel()
beam.tasks.wait(task)
factory.prepare_continuation(task)
factory.set(RepetitionTaskFactory.ITERATIONS, 7)
task = factory.create()
task.execute()
beam.tasks.wait(task)

if __name__ == '__main__':
main()

In actuality, we can take this decomposition one step further by factoring out from the HelloTask the responsibility of printing 'hello' with the responsibility of running a task after a specified period of time. If we so desired we would write a TimerTask/TimerTaskFactory and then our final composition would be along the lines of a RepetitionTaskFactory(TimerTaskFactory(HelloTaskFactory(), beam.threading.LiveTimer)).

TypeScript Style Guide

2018-09-05T15:53:06Z

Kman: /* Naming */

This article specifies the most general guidelines used for all Spire projects written using TypeScript as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern web development practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Development Environment=

The primary operating systems supported by Spire projects are Ubuntu 18.02 LTS, Windows 10, and macOS. On all systems, nodejs is used as the build system and webpack is used as the bundler.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice, however [https://code.visualstudio.com/ Visual Studio Code] is recommended.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The name of a file should correspond to the primary class that it exports.

The default extension for TypeScript files is ''ts''

The extension used for TypeScript files containing JSX is ''tsx''

All files end with a single new line character.

=Directory Structure=

A project is broken down into a library component, a test component, and one or more application components. These components are referred to as ''artifacts''. The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''setup'' to download and install any dependencies needed to produce the artifact and the ''build'' script which produces the artifact. Typically the ''setup'' script is run only once or when a new dependency is introduced to the project, and the ''build'' script is run anytime a new build is needed.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named sudoku the following directory structure should be used:

<pre>
sudoku # Root level directory.
build.sh # Script used to build all projects on POSIX.
build.bat # Script used to build all projects on Windows.
\applications # Contains all applications.
\sudoku # Contains the source for the sudoku web application.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
webpack.config.js # The Webpack configuration.
build.sh # Script used to build application on POSIX.
build.bat # Script used to build application Windows.
\source # Contains the web application source files.
\index.html # The HTML file that loads the JavaScript application.
\index.tsx # The TypeScript/JSX file containing the application.
\library # Contains the common library code.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
webpack.config.js # The Webpack configuration.
build.sh # Script used to build library on POSIX.
build.bat # Script used to build library on Windows.
\source # Contains the library source files.
index.ts # Exports all definitions contained in this directory.
\pages # Contains the source code for individual web pages.
index.ts # Exports all definitions for every web page defined
# in this directory.
\landing_page # Contains the source code for the landing page.
index.ts # Exports the landing page.
landing_page.tsx # The TypeScript/JSX source code for the landing page.
\page_2 # Contains the source for for another web page.
... # Structured in a similar manner as the landing page.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/sudoku

=Syntax=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=typescript line=line>
function factorial(n: number): number {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==

Statements must end with a semi-colon ';' or a closing brace '}', even in cases where TypeScript allows them to be optional.

Lines are limited to 80 characters. Exceptions to this rule are long imports and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=typescript line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=typescript line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=typescript line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=typescript line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=typescript line=line>
// Correct.
const x = a + b;
const y = 5;

//! Incorrect
const x = a+b;
const y=5;
const z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=typescript line=line>
// Correct.
f(1, 2);
function g(a: number, b: number): number;

//! Incorrect
f(1,2);
function g(a:number,b:number);
</syntaxhighlight>

==Naming==

[https://en.wikipedia.org/wiki/Camel_case Camel case] is used for naming whereas variables and functions use mixedCase and namespaces, modules, and types use CapWords. Names should be descriptive but should avoid being verbose.

Classes and variables should be given the name of a noun and functions the name of a verb. Functions that return a boolean or boolean variables should be named in the form of a question starting with isX or hasX.

==Imports==
Imports are listed in order of most global to local. Where dependencies have the same locality, then they are ordered alphabetically. For example, the first group of dependencies to be imported are third party packages which are listed in alphabetical order based on the package name. In the above snippet the third party dependencies are jquery, react and react-router-dom which are imported in alphabetical order. Then local dependencies are imported where directories further up the hierarchy are imported first. That is, the directory '../../..' which is three levels up is imported before the directory '..' which is only one level up.

When multiple names are imported from a package, they must be listed in alphabetical order.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '../../..';
import {Model} from '..';
</syntaxhighlight>

==Declarations==

Any declaration (such as a function or class) that is intended to be imported by another file must be documented using [http://usejsdoc.org/ JSDoc style]. If the definition is local then that documentation should be omitted entirely.

Any documentation should be preceded by a blank line. In the code snippet, Properties is part of the public API so it is documented along with all of its fields, but the State is internal to the file so no aspect of it is documented.

<syntaxhighlight lang=typescript line=line>

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}
</syntaxhighlight>

==Variable Declarations==

Variables are declared so that only one variable is declared per line, prefer declaring variables using ''const'' when possible, and deferring to ''let'' otherwise, variables should always be initialized at the point of their declaration.

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=typescript line=line>
const value = (() => {
if(condition) {
return 123;
}
return 321;
})();
</syntaxhighlight>

=Example=

Below is a full example combining numerous elements of the style guide to define a typical React component. It should be used as a general reference for how code is laid out, structured, and properly spaced.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '..';
import {Model} from '.';

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}

/** Displays an HTML page. */
export class Page extends React.Component<Properties, State> {
constructor(props: Properties) {
super(props);
this.state = {
redirect: '',
isLoading: true
};
}

public componentWillMount(): void {
this.props.model.load().then(
() => {
this.setState({
isLoading: false
});
});
}

public render(): JSX.Element {
if(this.state.redirect) {
return <Router.Redirect push to={this.state.redirect}/>;
} else if(this.state.isLoading) {
return <LoadingPage/>;
}
const style = {
backgroundColor: '#FFFFFF',
font: 'Roboto 14px'
};
return (
<div style={style}>
<h1>Hello world!</h1>
<img src='cat.jpg'/>
</div>);
}
}
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials for best practices on writing portable, efficient, and clean TypeScript:

* [https://www.typescriptlang.org/docs/handbook/basic-types.html TypeScript Hand Book]

TypeScript Style Guide

2018-09-04T02:47:44Z

Kman: /* Directory Structure */

This article specifies the most general guidelines used for all Spire projects written using TypeScript as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern web development practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Development Environment=

The primary operating systems supported by Spire projects are Ubuntu 18.02 LTS, Windows 10, and macOS. On all systems, nodejs is used as the build system and webpack is used as the bundler.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice, however [https://code.visualstudio.com/ Visual Studio Code] is recommended.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The name of a file should correspond to the primary class that it exports.

The default extension for TypeScript files is ''ts''

The extension used for TypeScript files containing JSX is ''tsx''

All files end with a single new line character.

=Directory Structure=

A project is broken down into a library component, a test component, and one or more application components. These components are referred to as ''artifacts''. The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''setup'' to download and install any dependencies needed to produce the artifact and the ''build'' script which produces the artifact. Typically the ''setup'' script is run only once or when a new dependency is introduced to the project, and the ''build'' script is run anytime a new build is needed.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named sudoku the following directory structure should be used:

<pre>
sudoku # Root level directory.
build.sh # Script used to build all projects on POSIX.
build.bat # Script used to build all projects on Windows.
\applications # Contains all applications.
\sudoku # Contains the source for the sudoku web application.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
webpack.config.js # The Webpack configuration.
build.sh # Script used to build application on POSIX.
build.bat # Script used to build application Windows.
\source # Contains the web application source files.
\index.html # The HTML file that loads the JavaScript application.
\index.tsx # The TypeScript/JSX file containing the application.
\library # Contains the common library code.
package.json # The Node JS package description.
tsconfig.json # The TypeScript compiler configuration.
webpack.config.js # The Webpack configuration.
build.sh # Script used to build library on POSIX.
build.bat # Script used to build library on Windows.
\source # Contains the library source files.
index.ts # Exports all definitions contained in this directory.
\pages # Contains the source code for individual web pages.
index.ts # Exports all definitions for every web page defined
# in this directory.
\landing_page # Contains the source code for the landing page.
index.ts # Exports the landing page.
landing_page.tsx # The TypeScript/JSX source code for the landing page.
\page_2 # Contains the source for for another web page.
... # Structured in a similar manner as the landing page.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/sudoku

=Syntax=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=typescript line=line>
function factorial(n: number): number {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==

Statements must end with a semi-colon ';' or a closing brace '}', even in cases where TypeScript allows them to be optional.

Lines are limited to 80 characters. Exceptions to this rule are long imports and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=typescript line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=typescript line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=typescript line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
console.log('meow');
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=typescript line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=typescript line=line>
// Correct.
const x = a + b;
const y = 5;

//! Incorrect
const x = a+b;
const y=5;
const z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=typescript line=line>
// Correct.
f(1, 2);
function g(a: number, b: number): number;

//! Incorrect
f(1,2);
function g(a:number,b:number);
</syntaxhighlight>

==Naming==

[https://en.wikipedia.org/wiki/Camel_case Camel case] is used for naming where variables and functions use mixedCase and namespaces, modules, and types use CapWords. Names should be descriptive but should avoid being verbose.

Classes and variables should be given the name of a noun and functions the name of a verb. Functions that return a boolean or boolean variables should be named in the form of a question starting with isX or hasX.

==Imports==
Imports are listed in order of most global to local. Where dependencies have the same locality, then they are ordered alphabetically. For example, the first group of dependencies to be imported are third party packages which are listed in alphabetical order based on the package name. In the above snippet the third party dependencies are jquery, react and react-router-dom which are imported in alphabetical order. Then local dependencies are imported where directories further up the hierarchy are imported first. That is, the directory '../../..' which is three levels up is imported before the directory '..' which is only one level up.

When multiple names are imported from a package, they must be listed in alphabetical order.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '../../..';
import {Model} from '..';
</syntaxhighlight>

==Declarations==

Any declaration (such as a function or class) that is intended to be imported by another file must be documented using [http://usejsdoc.org/ JSDoc style]. If the definition is local then that documentation should be omitted entirely.

Any documentation should be preceded by a blank line. In the code snippet, Properties is part of the public API so it is documented along with all of its fields, but the State is internal to the file so no aspect of it is documented.

<syntaxhighlight lang=typescript line=line>

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}
</syntaxhighlight>

==Variable Declarations==

Variables are declared so that only one variable is declared per line, prefer declaring variables using ''const'' when possible, and deferring to ''let'' otherwise, variables should always be initialized at the point of their declaration.

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=typescript line=line>
const value = (() => {
if(condition) {
return 123;
}
return 321;
})();
</syntaxhighlight>

=Example=

Below is a full example combining numerous elements of the style guide to define a typical React component. It should be used as a general reference for how code is laid out, structured, and properly spaced.

<syntaxhighlight lang=typescript line=line>
import * as $ from 'jquery';
import * as React from 'react';
import * as Router from 'react-router-dom';
import {HBoxLayout, Padding, VBoxLayout} from '..';
import {Model} from '.';

/** Stores the React properties used to render a Page. */
export interface Properties {

/** The model used to display the page. */
model: Model;
}

export interface State {
redirect: string;
isLoading: boolean;
}

/** Displays an HTML page. */
export class Page extends React.Component<Properties, State> {
constructor(props: Properties) {
super(props);
this.state = {
redirect: '',
isLoading: true
};
}

public componentWillMount(): void {
this.props.model.load().then(
() => {
this.setState({
isLoading: false
});
});
}

public render(): JSX.Element {
if(this.state.redirect) {
return <Router.Redirect push to={this.state.redirect}/>;
} else if(this.state.isLoading) {
return <LoadingPage/>;
}
const style = {
backgroundColor: '#FFFFFF',
font: 'Roboto 14px'
};
return (
<div style={style}>
<h1>Hello world!</h1>
<img src='cat.jpg'/>
</div>);
}
}
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials for best practices on writing portable, efficient, and clean TypeScript:

* [https://www.typescriptlang.org/docs/handbook/basic-types.html TypeScript Hand Book]

C++ Style Guide

2018-08-02T14:59:38Z

Kman: /* Namespaces */

This article specifies the most general guidelines used for all Spire projects written using C++ as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern C++ practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Core Guidelines=
This document should be seen as an extension to the Cpp Core Guidelines authored and maintained by Herb Sutter and Bjarne Stroustrup. After reviewing these guidelines one should then become familiar with the Cpp Core Guidelines as documented here:

https://github.com/isocpp/CppCoreGuidelines

Those guidelines specify the best practices for writing modern C++ code. In situations where there is a conflict between the Cpp Core Guidelines and the guidelines set forth in this document, this document takes precedence. For all known situations where a conflict exists, this document should explicitly indicate that conflict to avoid confusion.

=Development Environment=

The two primary development environments supported by Spire projects are Ubuntu Server 18.04 LTS and Windows 10. On POSIX systems the compiler of choice is g++ 7.3 and on Windows 10 it's Microsoft Visual Studio 2017 15.7.5. In order to support these two platforms, CMake is used to produce the appropriate project/make files for each platform.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice. [https://www.visualstudio.com/downloads/ Visual Studio 2017] is typically used for Windows and [https://code.visualstudio.com/ Visual Studio Code] is typically used on Linux and Mac.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The main exception is for CMake files which must use the name ''CMakeLists.txt''

Header files should use the extension ''hpp''

Source files should use the extension ''cpp''

All files end with a single new line character.

=Directory Structure=

A project is broken down into one library component and one or more application components. These components are referred to as ''artifacts''. The library is written in a [https://en.wikipedia.org/wiki/Header-only header-only fashion], that is the implementation is provided directly in the header file rather than a separate .cpp source file. This allows for such libraries to easily be incorporated into other projects without the need for complex build configurations. Applications often use a mix of header only files and source files.

The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts and CMake files needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''run_cmake'' to produce the platform specific build files (make files for POSIX and VS solutions for Windows), ''version'' to produce a header file that contains the version of the artifact produced and the ''build'' script which produces the artifact. In order to build an artifact, one first produces the build files for their platform by running the ''run_cmake'' script, and then they can run the ''build'' script afterwards to produce the artifact.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named tic_tac_toe consisting of applications tic_tac_toe_console and tic_tac_toe_ui sharing code common to both applications, the following directory structure should be used:

<pre>
tic_tac_toe # Root level directory.
\applications # Contains all applications.
\tic_tac_toe_console # Contains the source for a console application.
\build # Files/scripts used to build the console tic-tac-toe game.
\config # Contains all CMake build files.
CMakeLists.txt # The CMake config file for the overall application.
\tic_tac_toe_console # Contains CMake build files for the main executable.
\CMakeLists.txt # The CMake config file for the executable.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the application.
\run_cmake.sh # Script used to produce the make/build files.
\set_env.sh # Script defining the environment variables.
\version.sh # Script that produces the VERSION stamped header file.
\windows # Contains scripts to build on Windows.
\build.bat # Script used to build the application.
\run_cmake.bat # Script used to produce the VS solution.
\set_env.bat # Script defining environment variables.
\version.bat # Script that produces the VERSION stamped header file.
\source # Contains the C++ source files.
\tic_tac_toe_console # Contains the file defining the main function.
\main.cpp # Defines the main function.
\source_dir_a # Contains additional source files specific the console.
\source_a.cpp # C++ source code files.
\source_b.cpp
\source_c.cpp
\source_dir_b # Contains additional source files specific the console.
\source_d.cpp
\source_e.cpp
\source_f.cpp
\tic_tac_toe_ui # Contains a GUI version of tic-tac-toe.
\... # The structure is similar to the console application.
\build # Contains build scripts to build the entire project.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Builds all libraries and applications.
\local_build.sh # A helper script containing common build functions.
\run_cmake.sh # Produces all project make/build files.
\setup.sh # Installs all third party dependencies.
\windows # Contains scripts to build on Windows.
\build.bat # Builds all libraries and applications.
\run_cmake.bat # Produces all VS solutions.
\setup.bat # Installs all third party dependencies.
\library # Contains the common library code.
\build # Files/script used to build the library.
\config # Contains all CMake build files.
\CMakeLists.txt # The CMake config file for the library.
\dir_a # Contains CMake build files for library component A.
\CMakeLists.txt # The CMake config file to build component A and unit tests.
\dir_b # Contains CMake build files for library component B.
\CMakeLists.txt # The CMake config file to build component B and unit tests.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the library.
\run_cmake.sh # Script used to produce make/build files.
\set_env.sh # Script defining the environment variables.
\windows # Contains scripts to build on Windows.
\build.bat # Script to build the library.
\run_cmake.bat # Script to produce the VS solution.
\set_env.bat # Script defining the environment variables.
\include # Contains the library header files (.hpp)
\tic_tac_toe
\tic_tac_toe # Contains the top-most generic library header files.
\tic_tac_toe.hpp # Header file containing generic forward declarations.
\dir_a # Contains header files for library component A.
\a.hpp # Header file containing forward declarations for component A.
\a_header_1.hpp # Header file for library component A.
\a_header_2.hpp
\a_header_3.hpp
\dir_b
\b.hpp # Header file containing forward declarations for component B.
\b_header_1.hpp # Contains header files for library component B.
\b_header_2.hpp
\b_header_3.hpp
\source # Contains the library source files (.cpp)
\tic_tac_toe # Dummy directory for the overall library.
\dummy.cpp # Dummy source code file.
\dir_a # Dummy directory for library component A.
\dummy.cpp # Dummy source file.
\dir_a_tester # Contains unit tests for library component A.
\a_header_1_tester.cpp # Contains unit tests for definitions in a_header_1.hpp
\a_header_2_tester.cpp
\a_header_3_tester.cpp
\main.cpp # The entry point for component A unit tests.
\dir_b # Dummy directory for library component B.
\dummy.cpp # Dummy source file.
\dir_b_tester # Contains unit tests for library component B.
\b_header_1_tester.cpp # Contains unit tests for definitions in b_header_a.hpp
\b_header_2_tester.cpp
\b_header_3_tester.cpp
\main.cpp # The entry point for component B unit tests.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/tic_tac_toe

=Header File Structure=

==Include Guard==
Header files are structured first with an [https://en.wikipedia.org/wiki/Include_guard include guard] defined using capital letter snake case whose name consists of the project name appended to the directory name and finally the file name itself. As a note, all files end with a single new line character.
<syntaxhighlight lang=c++ line=line>
#ifndef CPP_CHAT_SERVER_HPP
#define CPP_CHAT_SERVER_HPP
...
#endif
</syntaxhighlight>

==Include Directives==
Next come the list of #include directives. Include files are ordered based on their category where the first category is standard C++ header files, the second category is external dependency header files, and finally the third category is project header files. Both standard and external dependency header files use angle brackets (#include <...>) and local project header files use quotes (#include "..."). Within each category files are listed in alphabetical order.
<syntaxhighlight lang=c++ line=line>
#include <tuple>
#include <vector>
#include <boost/noncopyable.hpp>
#include "cpp_chat/cpp_chat.hpp"
#include "cpp_chat/definitions.hpp"
</syntaxhighlight>

==Namespaces==
After include directives the project's namespace is defined. All declarations and definitions must be contained within a namespace so as to avoid polluting the global namespace. Namespace definitions should be preceded by one single new line except when immediately following a namespace definition. The top level namespace is named after the project, and sub-namespaces may be used (although they should be used very sparingly).

<syntaxhighlight lang=c++ line=line>
namespace CppChat {
namespace SubChatA {
...
}

namespace SubChatB {
namespace SubSubChatA {
...
}
}
}

namespace CppChatExtra {
...
}
</syntaxhighlight>

One situation where nested namespaces are welcome and encouraged are for implementation details that do not form part of the namespace's public interface. These definitions are put in a nested namespace called ''Details'' and go into a file of their own whose name contains the suffix ''details''. For example if the ''cpp_chat_server.hpp'' contains implementation details, then they should be included in the file ''cpp_chat_server_details.hpp'' and the definitions should go into the namespace ''CppChat::Details''.

=Layout=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=c++ line=line>
int factorial(int n) {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==
Lines are limited to 80 characters. Exceptions to this rule are long include files and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=c++ line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=c++ line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=c++ line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=c++ line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=c++ line=line>
// Correct.
auto x = a + b;
auto y = 5;

//! Incorrect
auto x = a+b;
auto y=5;
auto z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=c++ line=line>
// Correct.
f(1, 2);
int g(int a, int b);

//! Incorrect
f(1,2);
int g(int a,int b);
</syntaxhighlight>

=Syntax=

==Function Definitions==

Functions declared and defined in header files are formatted as follows:
<syntaxhighlight lang=c++ line=line>
inline int f() {
...
return 123;
}

template<typename T>
bool g() {
...
return false;
}
</syntaxhighlight>

That is they are declared as inline unless they are function templates in which case the inline specified is omitted.

==Variable Declarations==

Variables are declared so that only one variable is declared per line, the type of the variable should [https://herbsutter.com/2013/08/12/gotw-94-solution-aaa-style-almost-always-auto/ almost always use auto], and variables should almost always be initialized.

Examples of simple declarations:
<syntaxhighlight lang=c++ line=line>
auto x = 5;
auto y = a + b;
</syntaxhighlight>

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=c++ line=line>
auto value = [&] {
if(condition) {
return 123;
}
return 321;
}();
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials (both online and published) for best practices on writing portable, efficient, and clean C++ code:

* S. Meyers, ''Effective Modern C++''. 2014
* B. Stroustrup ''The C++ Programming Language (4th Edition)''. 2013
* [https://github.com/isocpp/CppCoreGuidelines Cpp Core Guidelines]
* [https://isocpp.org/ Standard C++ Blog]
* [https://cppcon.org/ CppCon - The C++ Conference]

C++ Style Guide

2018-08-02T14:59:07Z

Kman: /* Namespaces */

This article specifies the most general guidelines used for all Spire projects written using C++ as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern C++ practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Core Guidelines=
This document should be seen as an extension to the Cpp Core Guidelines authored and maintained by Herb Sutter and Bjarne Stroustrup. After reviewing these guidelines one should then become familiar with the Cpp Core Guidelines as documented here:

https://github.com/isocpp/CppCoreGuidelines

Those guidelines specify the best practices for writing modern C++ code. In situations where there is a conflict between the Cpp Core Guidelines and the guidelines set forth in this document, this document takes precedence. For all known situations where a conflict exists, this document should explicitly indicate that conflict to avoid confusion.

=Development Environment=

The two primary development environments supported by Spire projects are Ubuntu Server 18.04 LTS and Windows 10. On POSIX systems the compiler of choice is g++ 7.3 and on Windows 10 it's Microsoft Visual Studio 2017 15.7.5. In order to support these two platforms, CMake is used to produce the appropriate project/make files for each platform.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice. [https://www.visualstudio.com/downloads/ Visual Studio 2017] is typically used for Windows and [https://code.visualstudio.com/ Visual Studio Code] is typically used on Linux and Mac.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The main exception is for CMake files which must use the name ''CMakeLists.txt''

Header files should use the extension ''hpp''

Source files should use the extension ''cpp''

All files end with a single new line character.

=Directory Structure=

A project is broken down into one library component and one or more application components. These components are referred to as ''artifacts''. The library is written in a [https://en.wikipedia.org/wiki/Header-only header-only fashion], that is the implementation is provided directly in the header file rather than a separate .cpp source file. This allows for such libraries to easily be incorporated into other projects without the need for complex build configurations. Applications often use a mix of header only files and source files.

The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts and CMake files needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''run_cmake'' to produce the platform specific build files (make files for POSIX and VS solutions for Windows), ''version'' to produce a header file that contains the version of the artifact produced and the ''build'' script which produces the artifact. In order to build an artifact, one first produces the build files for their platform by running the ''run_cmake'' script, and then they can run the ''build'' script afterwards to produce the artifact.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named tic_tac_toe consisting of applications tic_tac_toe_console and tic_tac_toe_ui sharing code common to both applications, the following directory structure should be used:

<pre>
tic_tac_toe # Root level directory.
\applications # Contains all applications.
\tic_tac_toe_console # Contains the source for a console application.
\build # Files/scripts used to build the console tic-tac-toe game.
\config # Contains all CMake build files.
CMakeLists.txt # The CMake config file for the overall application.
\tic_tac_toe_console # Contains CMake build files for the main executable.
\CMakeLists.txt # The CMake config file for the executable.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the application.
\run_cmake.sh # Script used to produce the make/build files.
\set_env.sh # Script defining the environment variables.
\version.sh # Script that produces the VERSION stamped header file.
\windows # Contains scripts to build on Windows.
\build.bat # Script used to build the application.
\run_cmake.bat # Script used to produce the VS solution.
\set_env.bat # Script defining environment variables.
\version.bat # Script that produces the VERSION stamped header file.
\source # Contains the C++ source files.
\tic_tac_toe_console # Contains the file defining the main function.
\main.cpp # Defines the main function.
\source_dir_a # Contains additional source files specific the console.
\source_a.cpp # C++ source code files.
\source_b.cpp
\source_c.cpp
\source_dir_b # Contains additional source files specific the console.
\source_d.cpp
\source_e.cpp
\source_f.cpp
\tic_tac_toe_ui # Contains a GUI version of tic-tac-toe.
\... # The structure is similar to the console application.
\build # Contains build scripts to build the entire project.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Builds all libraries and applications.
\local_build.sh # A helper script containing common build functions.
\run_cmake.sh # Produces all project make/build files.
\setup.sh # Installs all third party dependencies.
\windows # Contains scripts to build on Windows.
\build.bat # Builds all libraries and applications.
\run_cmake.bat # Produces all VS solutions.
\setup.bat # Installs all third party dependencies.
\library # Contains the common library code.
\build # Files/script used to build the library.
\config # Contains all CMake build files.
\CMakeLists.txt # The CMake config file for the library.
\dir_a # Contains CMake build files for library component A.
\CMakeLists.txt # The CMake config file to build component A and unit tests.
\dir_b # Contains CMake build files for library component B.
\CMakeLists.txt # The CMake config file to build component B and unit tests.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the library.
\run_cmake.sh # Script used to produce make/build files.
\set_env.sh # Script defining the environment variables.
\windows # Contains scripts to build on Windows.
\build.bat # Script to build the library.
\run_cmake.bat # Script to produce the VS solution.
\set_env.bat # Script defining the environment variables.
\include # Contains the library header files (.hpp)
\tic_tac_toe
\tic_tac_toe # Contains the top-most generic library header files.
\tic_tac_toe.hpp # Header file containing generic forward declarations.
\dir_a # Contains header files for library component A.
\a.hpp # Header file containing forward declarations for component A.
\a_header_1.hpp # Header file for library component A.
\a_header_2.hpp
\a_header_3.hpp
\dir_b
\b.hpp # Header file containing forward declarations for component B.
\b_header_1.hpp # Contains header files for library component B.
\b_header_2.hpp
\b_header_3.hpp
\source # Contains the library source files (.cpp)
\tic_tac_toe # Dummy directory for the overall library.
\dummy.cpp # Dummy source code file.
\dir_a # Dummy directory for library component A.
\dummy.cpp # Dummy source file.
\dir_a_tester # Contains unit tests for library component A.
\a_header_1_tester.cpp # Contains unit tests for definitions in a_header_1.hpp
\a_header_2_tester.cpp
\a_header_3_tester.cpp
\main.cpp # The entry point for component A unit tests.
\dir_b # Dummy directory for library component B.
\dummy.cpp # Dummy source file.
\dir_b_tester # Contains unit tests for library component B.
\b_header_1_tester.cpp # Contains unit tests for definitions in b_header_a.hpp
\b_header_2_tester.cpp
\b_header_3_tester.cpp
\main.cpp # The entry point for component B unit tests.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/tic_tac_toe

=Header File Structure=

==Include Guard==
Header files are structured first with an [https://en.wikipedia.org/wiki/Include_guard include guard] defined using capital letter snake case whose name consists of the project name appended to the directory name and finally the file name itself. As a note, all files end with a single new line character.
<syntaxhighlight lang=c++ line=line>
#ifndef CPP_CHAT_SERVER_HPP
#define CPP_CHAT_SERVER_HPP
...
#endif
</syntaxhighlight>

==Include Directives==
Next come the list of #include directives. Include files are ordered based on their category where the first category is standard C++ header files, the second category is external dependency header files, and finally the third category is project header files. Both standard and external dependency header files use angle brackets (#include <...>) and local project header files use quotes (#include "..."). Within each category files are listed in alphabetical order.
<syntaxhighlight lang=c++ line=line>
#include <tuple>
#include <vector>
#include <boost/noncopyable.hpp>
#include "cpp_chat/cpp_chat.hpp"
#include "cpp_chat/definitions.hpp"
</syntaxhighlight>

==Namespaces==
After include directives the project's namespace is defined. All declarations and definitions must be contained within a namespace so as to avoid polluting the global namespace. Namespace definitions should be preceded by one single new line except when immediately following a namespace definition. The top level namespace is named after the project, and sub-namespaces may be used (although they should be used very sparingly).

<syntaxhighlight lang=c++ line=line>
namespace CppChat {
namespace SubChatA {
...
}

namespace SubChatB {
namespace SubSubChatA {
...
}
}
}

namespace CppChatExtra {
...
}
</syntaxhighlight>

One situation where nested namespaces are welcome and encouraged are for implementation details that do not form part of the namespace's public interface. These definitions are put in a nested namespace called ''details'' and go into a file of their own whose name contains the suffix ''details''. For example if the ''cpp_chat_server.hpp'' contains implementation details, then they should be included in the file ''cpp_chat_server_details.hpp'' and the definitions should go into the namespace ''cpp_chat::details''.

=Layout=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=c++ line=line>
int factorial(int n) {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==
Lines are limited to 80 characters. Exceptions to this rule are long include files and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=c++ line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=c++ line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=c++ line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=c++ line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=c++ line=line>
// Correct.
auto x = a + b;
auto y = 5;

//! Incorrect
auto x = a+b;
auto y=5;
auto z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=c++ line=line>
// Correct.
f(1, 2);
int g(int a, int b);

//! Incorrect
f(1,2);
int g(int a,int b);
</syntaxhighlight>

=Syntax=

==Function Definitions==

Functions declared and defined in header files are formatted as follows:
<syntaxhighlight lang=c++ line=line>
inline int f() {
...
return 123;
}

template<typename T>
bool g() {
...
return false;
}
</syntaxhighlight>

That is they are declared as inline unless they are function templates in which case the inline specified is omitted.

==Variable Declarations==

Variables are declared so that only one variable is declared per line, the type of the variable should [https://herbsutter.com/2013/08/12/gotw-94-solution-aaa-style-almost-always-auto/ almost always use auto], and variables should almost always be initialized.

Examples of simple declarations:
<syntaxhighlight lang=c++ line=line>
auto x = 5;
auto y = a + b;
</syntaxhighlight>

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=c++ line=line>
auto value = [&] {
if(condition) {
return 123;
}
return 321;
}();
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials (both online and published) for best practices on writing portable, efficient, and clean C++ code:

* S. Meyers, ''Effective Modern C++''. 2014
* B. Stroustrup ''The C++ Programming Language (4th Edition)''. 2013
* [https://github.com/isocpp/CppCoreGuidelines Cpp Core Guidelines]
* [https://isocpp.org/ Standard C++ Blog]
* [https://cppcon.org/ CppCon - The C++ Conference]

C++ Style Guide

2018-08-02T14:57:01Z

Kman: /* Development Environment */

This article specifies the most general guidelines used for all Spire projects written using C++ as the primary programming language. Each individual project may extend or override the guidelines specified herein. The overall aim of this guideline is to provide consistency across the numerous projects developed by Spire in order to promote and benefit from modern C++ practices as well as tailor them to our specific requirements.

In general, the guidelines are very specific and opinionated. This is done intentionally to ensure that every detail has been given proper consideration and that every line of code is written with care and diligence. It is taken as a prerequisite that writing robust, clean and maintainable code requires paying close attention to even the smallest of details. As such, when there are two or more ways to write or express any given statement or expression, be it using spaces or tabs, number of characters per line, purple or violet, the guideline will often require that one particular approach be used to the exclusion of others.

Finally, this document is constantly evolving and as such older projects may not be up-to-date with the guidelines found here. In those circumstances one must use their best judgment about how to integrate these guidelines into older codebases. As a general principle, consistency should favor the local over the global, that is it is more important to be consistent with a function definition than within a file, and more important to be consistent within a file than within a directory, project, etc...

=Core Guidelines=
This document should be seen as an extension to the Cpp Core Guidelines authored and maintained by Herb Sutter and Bjarne Stroustrup. After reviewing these guidelines one should then become familiar with the Cpp Core Guidelines as documented here:

https://github.com/isocpp/CppCoreGuidelines

Those guidelines specify the best practices for writing modern C++ code. In situations where there is a conflict between the Cpp Core Guidelines and the guidelines set forth in this document, this document takes precedence. For all known situations where a conflict exists, this document should explicitly indicate that conflict to avoid confusion.

=Development Environment=

The two primary development environments supported by Spire projects are Ubuntu Server 18.04 LTS and Windows 10. On POSIX systems the compiler of choice is g++ 7.3 and on Windows 10 it's Microsoft Visual Studio 2017 15.7.5. In order to support these two platforms, CMake is used to produce the appropriate project/make files for each platform.

For source control, git is used and projects are to be hosted on [https://github.com/spiretrading Spire Trading's Github page].

Each developer is welcome to use an editor of their choice. [https://www.visualstudio.com/downloads/ Visual Studio 2017] is typically used for Windows and [https://code.visualstudio.com/ Visual Studio Code] is typically used on Linux and Mac.

=File Names=

Use [https://en.wikipedia.org/wiki/Snake_case snake case] using all lower case letters for files and directories. The main exception is for CMake files which must use the name ''CMakeLists.txt''

Header files should use the extension ''hpp''

Source files should use the extension ''cpp''

All files end with a single new line character.

=Directory Structure=

A project is broken down into one library component and one or more application components. These components are referred to as ''artifacts''. The library is written in a [https://en.wikipedia.org/wiki/Header-only header-only fashion], that is the implementation is provided directly in the header file rather than a separate .cpp source file. This allows for such libraries to easily be incorporated into other projects without the need for complex build configurations. Applications often use a mix of header only files and source files.

The applications go into their own ''applications'' directory and the libraries into the ''library'' directory. Within each artifact is a ''build'' directory containing the build scripts and CMake files needed to build that artifact. Scripts for POSIX systems are found in the ''posix'' sub-directory and Windows build files are within the ''windows'' sub-directory. The build scripts specified are ''run_cmake'' to produce the platform specific build files (make files for POSIX and VS solutions for Windows), ''version'' to produce a header file that contains the version of the artifact produced and the ''build'' script which produces the artifact. In order to build an artifact, one first produces the build files for their platform by running the ''run_cmake'' script, and then they can run the ''build'' script afterwards to produce the artifact.

Finally there is a top-level ''build'' directory for the project as a whole which produces all artifacts by recursively calling each artifact's individual build scripts. Additionally the top-level build directory also includes a ''setup'' script which downloads all third party dependencies. Some projects may also opt to include an ''install'' script which sets up a suitable development environment, and other scripts for continuous builds, deployment and testing.

Assuming a project named tic_tac_toe consisting of applications tic_tac_toe_console and tic_tac_toe_ui sharing code common to both applications, the following directory structure should be used:

<pre>
tic_tac_toe # Root level directory.
\applications # Contains all applications.
\tic_tac_toe_console # Contains the source for a console application.
\build # Files/scripts used to build the console tic-tac-toe game.
\config # Contains all CMake build files.
CMakeLists.txt # The CMake config file for the overall application.
\tic_tac_toe_console # Contains CMake build files for the main executable.
\CMakeLists.txt # The CMake config file for the executable.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the application.
\run_cmake.sh # Script used to produce the make/build files.
\set_env.sh # Script defining the environment variables.
\version.sh # Script that produces the VERSION stamped header file.
\windows # Contains scripts to build on Windows.
\build.bat # Script used to build the application.
\run_cmake.bat # Script used to produce the VS solution.
\set_env.bat # Script defining environment variables.
\version.bat # Script that produces the VERSION stamped header file.
\source # Contains the C++ source files.
\tic_tac_toe_console # Contains the file defining the main function.
\main.cpp # Defines the main function.
\source_dir_a # Contains additional source files specific the console.
\source_a.cpp # C++ source code files.
\source_b.cpp
\source_c.cpp
\source_dir_b # Contains additional source files specific the console.
\source_d.cpp
\source_e.cpp
\source_f.cpp
\tic_tac_toe_ui # Contains a GUI version of tic-tac-toe.
\... # The structure is similar to the console application.
\build # Contains build scripts to build the entire project.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Builds all libraries and applications.
\local_build.sh # A helper script containing common build functions.
\run_cmake.sh # Produces all project make/build files.
\setup.sh # Installs all third party dependencies.
\windows # Contains scripts to build on Windows.
\build.bat # Builds all libraries and applications.
\run_cmake.bat # Produces all VS solutions.
\setup.bat # Installs all third party dependencies.
\library # Contains the common library code.
\build # Files/script used to build the library.
\config # Contains all CMake build files.
\CMakeLists.txt # The CMake config file for the library.
\dir_a # Contains CMake build files for library component A.
\CMakeLists.txt # The CMake config file to build component A and unit tests.
\dir_b # Contains CMake build files for library component B.
\CMakeLists.txt # The CMake config file to build component B and unit tests.
\posix # Contains scripts to build on POSIX systems.
\build.sh # Script used to build the library.
\run_cmake.sh # Script used to produce make/build files.
\set_env.sh # Script defining the environment variables.
\windows # Contains scripts to build on Windows.
\build.bat # Script to build the library.
\run_cmake.bat # Script to produce the VS solution.
\set_env.bat # Script defining the environment variables.
\include # Contains the library header files (.hpp)
\tic_tac_toe
\tic_tac_toe # Contains the top-most generic library header files.
\tic_tac_toe.hpp # Header file containing generic forward declarations.
\dir_a # Contains header files for library component A.
\a.hpp # Header file containing forward declarations for component A.
\a_header_1.hpp # Header file for library component A.
\a_header_2.hpp
\a_header_3.hpp
\dir_b
\b.hpp # Header file containing forward declarations for component B.
\b_header_1.hpp # Contains header files for library component B.
\b_header_2.hpp
\b_header_3.hpp
\source # Contains the library source files (.cpp)
\tic_tac_toe # Dummy directory for the overall library.
\dummy.cpp # Dummy source code file.
\dir_a # Dummy directory for library component A.
\dummy.cpp # Dummy source file.
\dir_a_tester # Contains unit tests for library component A.
\a_header_1_tester.cpp # Contains unit tests for definitions in a_header_1.hpp
\a_header_2_tester.cpp
\a_header_3_tester.cpp
\main.cpp # The entry point for component A unit tests.
\dir_b # Dummy directory for library component B.
\dummy.cpp # Dummy source file.
\dir_b_tester # Contains unit tests for library component B.
\b_header_1_tester.cpp # Contains unit tests for definitions in b_header_a.hpp
\b_header_2_tester.cpp
\b_header_3_tester.cpp
\main.cpp # The entry point for component B unit tests.
</pre>

An example of the above directory structure containing a basic skeletal implementation of all files can be found here: https://github.com/spiretrading/tic_tac_toe

=Header File Structure=

==Include Guard==
Header files are structured first with an [https://en.wikipedia.org/wiki/Include_guard include guard] defined using capital letter snake case whose name consists of the project name appended to the directory name and finally the file name itself. As a note, all files end with a single new line character.
<syntaxhighlight lang=c++ line=line>
#ifndef CPP_CHAT_SERVER_HPP
#define CPP_CHAT_SERVER_HPP
...
#endif
</syntaxhighlight>

==Include Directives==
Next come the list of #include directives. Include files are ordered based on their category where the first category is standard C++ header files, the second category is external dependency header files, and finally the third category is project header files. Both standard and external dependency header files use angle brackets (#include <...>) and local project header files use quotes (#include "..."). Within each category files are listed in alphabetical order.
<syntaxhighlight lang=c++ line=line>
#include <tuple>
#include <vector>
#include <boost/noncopyable.hpp>
#include "cpp_chat/cpp_chat.hpp"
#include "cpp_chat/definitions.hpp"
</syntaxhighlight>

==Namespaces==
After include directives the project's namespace is defined. All declarations and definitions must be contained within a namespace so as to avoid polluting the global namespace. Namespace definitions should be preceded by one single new line except when immediately following a namespace definition. The top level namespace is named after the project, and sub-namespaces may be used (although they should be used very sparingly).

<syntaxhighlight lang=c++ line=line>
namespace cpp_chat {
namespace sub_chat_a {
...
}

namespace sub_chat_b {
namespace sub_sub_chat_a {
...
}
}
}

namespace cpp_chat_extra {
...
}
</syntaxhighlight>

One situation where nested namespaces are welcome and encouraged are for implementation details that do not form part of the namespace's public interface. These definitions are put in a nested namespace called ''details'' and go into a file of their own whose name contains the suffix ''details''. For example if the ''cpp_chat_server.hpp'' contains implementation details, then they should be included in the file ''cpp_chat_server_details.hpp'' and the definitions should go into the namespace ''cpp_chat::details''.

=Layout=

==Indentation==
Code is indented using 2 spaces per level, tabs are not permitted.

<syntaxhighlight lang=c++ line=line>
int factorial(int n) {
if(n == 0) {
return 1;
}
return n * factorial(n - 1);
}
</syntaxhighlight>

==Line Structure==
Lines are limited to 80 characters. Exceptions to this rule are long include files and long string literals where breaking up the literal into multiple lines is not possible. In order to break up long statements into multiple lines the following rules are used:

* Break the line at a comma, operator or opening bracket.
<syntaxhighlight lang=c++ line=line>

// Correct, line break at comma.
f(a, ..., b,
c, ..., d);

// Incorrect, line break after expression.
f(a, ..., b
, c, ..., d);

// Correct, line break after operator.
a + ... + b +
c + ... + d;

// Incorrect, line break after expression.
a + ... + b
+ c + ... + d;

// Correct, line break after opening bracket.
f(
a, ..., b, c, ..., d);

// Incorrect, line break after function name.
f
(a, ..., b, c, ..., d);
</syntaxhighlight>

* For statements that begin new blocks of code (such as if/while/class...), in order to avoid confusing the line continuation with the code block, the line continuation is indented two extra levels. For example consider the following snippet of code:

<syntaxhighlight lang=c++ line=line>
// Incorrect.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The line continuation on line 2 clashes with the code block on line 3. To avoid this clash the above code is indented as follows:

<syntaxhighlight lang=c++ line=line>
// Correct.
if(condition_a && condition_b && ... &&
condition_c) {
std::cout << "meow" << std::endl;
}
</syntaxhighlight>

The extra level of indentation in the line continuation makes it clear where the condition ends and the code block begins.

==Braces==

Braces are placed using a variant of the [http://wiki.c2.com/?OneTrueBraceStyle OTBS style]. The opening brace is placed on the same line as the declaring statement with one single space preceding it, and the closing brace is placed on a line of its own at the same level of indentation as the declaring statement. For if statements, the else/else if is placed on the same line as the closing brace. For do/while loops, the while is placed on the same line as the closing brace.

Examples:
<syntaxhighlight lang=c++ line=line>
// Correct.
if(<cond>) {
<body>
} else {
<default>
}

// Correct.
do {
<body>
} while(<cond>);

// Incorrect.
if(<cond>)
{
<body>
}
else
{
<default>
}

// Incorrect.
do
{
<body>
}
while(<cond>);
</syntaxhighlight>

==Spacing==

The following are correct use cases for white spaces:

* Used for indentation.
* Used to surround binary operations.
<syntaxhighlight lang=c++ line=line>
// Correct.
auto x = a + b;
auto y = 5;

//! Incorrect
auto x = a+b;
auto y=5;
auto z= 5;
</syntaxhighlight>

* One space is placed after a comma.
<syntaxhighlight lang=c++ line=line>
// Correct.
f(1, 2);
int g(int a, int b);

//! Incorrect
f(1,2);
int g(int a,int b);
</syntaxhighlight>

=Syntax=

==Function Definitions==

Functions declared and defined in header files are formatted as follows:
<syntaxhighlight lang=c++ line=line>
inline int f() {
...
return 123;
}

template<typename T>
bool g() {
...
return false;
}
</syntaxhighlight>

That is they are declared as inline unless they are function templates in which case the inline specified is omitted.

==Variable Declarations==

Variables are declared so that only one variable is declared per line, the type of the variable should [https://herbsutter.com/2013/08/12/gotw-94-solution-aaa-style-almost-always-auto/ almost always use auto], and variables should almost always be initialized.

Examples of simple declarations:
<syntaxhighlight lang=c++ line=line>
auto x = 5;
auto y = a + b;
</syntaxhighlight>

For complex initialization of values, use an [https://en.wikipedia.org/wiki/Immediately-invoked_function_expression immediately invoked lambda expression] as follows:

<syntaxhighlight lang=c++ line=line>
auto value = [&] {
if(condition) {
return 123;
}
return 321;
}();
</syntaxhighlight>

=Additional References=

The bulk of this style guide focuses on syntax rather than good programming practices. The following list are reference materials (both online and published) for best practices on writing portable, efficient, and clean C++ code:

* S. Meyers, ''Effective Modern C++''. 2014
* B. Stroustrup ''The C++ Programming Language (4th Edition)''. 2013
* [https://github.com/isocpp/CppCoreGuidelines Cpp Core Guidelines]
* [https://isocpp.org/ Standard C++ Blog]
* [https://cppcon.org/ CppCon - The C++ Conference]

Workflow

2018-06-21T01:55:20Z

Kman: Created page with "The following workflow is used to ensure the timely and organized delivery of most software development related tasks. Each software developer is assigned to one or more proje..."

The following workflow is used to ensure the timely and organized delivery of most software development related tasks. Each software developer is assigned to one or more projects that they are expected to contribute to, and the management of these projects is handled using [https://www.manuscript.com/ Manuscript] (formerly known as Fogbugz).

To begin, login to Manuscript using your e-mail address and subscribe to your assigned projects. Doing so ensures that you are notified by e-mail of any updates made to your project. Subscribing to your projects involves first clicking on your avatar located at the bottom left corner of the page (indicated by the green arrow), and then clicking on the Subscribe menu item (indicated by the red arrow):

[[File:Workflow_subscribe.png]]

Choose to Add New Subscription:

[[File:Workflow_new_subscription.png]]

Individually select all projects assigned to you from the drop down menu:

[[File:Workflow_project_subscription.png]]

At this point your list of subscriptions should look like the below image indicating that you are subscribed to all assigned projects.

[[File:Workflow_subscription_final.png]]

File:Workflow subscription final.png

2018-06-21T01:55:05Z

Kman: