This topic explains how the Lock and Unlock operators (and the related Lock Set data construct) work together, and the actions you can take on their Properties views.
Important
Use of Lock and Unlock operators should be avoided if at all possible. By their very nature they will impede performance of the StreamBase application. Lock and Unlock operators can be thought of in the same light as exclusive locks in a relational database. Database designers try to avoid the use of exclusive locks because they impede performance. In fact, starting in StreamBase 3.0.0, you may be able to remove any existing Lock/Unlock pairs and Lock Sets from applications built with pre-3.0.0 StreamBase software. The Event Processing Platform in StreamBase provides a predictable execution order. This means that input tuples are each processed individually to completion, from left-to-right through a StreamBase EventFlow. There are exceptions to this general rule, as explained in the topic Execution Order, Concurrency, and Parallelism. Note that you may need to retain or add Lock, Unlock and a Lock Set if the processing of the components between (and including) your Lock and Unlock operators is distributed across more than one module reference or physical machine.
The Lock and Unlock operators work in conjunction to provide exclusive access to a critical section of an application. Lock and Unlock operators use key fields and expressions to control access to the critical sections of an application. Lock Sets are used to specify the fields in the key. Pairs of Lock and Unlock operators must have the same Lock Set associated with them. The list of expressions in Lock an Unlock operators must evaluate exactly to the same types as the fields defined in the schemas used in the Lock Sets. For example if the Lock Set has 2 fields, an int and a boolean, you must have two expressions in the Lock and Unlock operators that evaluate to an int and a boolean. In general, the expressions in the Lock and Unlock operators should be the same so that the Lock and Unlock operators will work in tandem.
When a tuple enters a Lock operator the expressions in the operator will be applied against the fields in the tuples. The expressions will generate a value X. Only one tuple that corresponds to the value X will be allowed past the Lock operators at any one time. All other tuples that evaluate to the value X will be buffered. Tuples that evaluate to values other than X will be allowed into the locked portion using the same rules. A locked portion of a StreamBase application may have multiple tuples but the values that they evaluate to must be distinct.
When a tuple enters an Unlock operator the expressions in the operator will be applied against the fields in the tuple just as in the Lock operator. If the expressions generate the value X (assuming that the Lock and Unlock operator have the same Lock Sets and expressions) then a tuple will be released from the paired Lock operator in FIFO order into the critical section of the application.
Care must be taken to ensure that the buffering in the Lock operator is stable. An Unlock operator must be able to release tuples from the Lock operator at least as fast as they are buffered in the Lock operator. Otherwise the application will become unstable as the buffer in the Lock operator will grow using up all available memory.
The Lock Set schema is probably different than the schemas of the input streams entering the Lock and Unlock operators. For example, the input stream schemas may have 5 fields but you only wish to lock and unlock on one of those fields. Therefore the Lock Set schema will only have one field.
To associate a Lock Set data construct and a Lock or Unlock Operator in StreamBase Studio, create an arc between the bottom port of the operator and the port on the top of the Lock Set.
The Lock and Unlock operators both accept a single input stream, and both produce one output stream whose output fields map one to one with the input fields. The Lock and Unlock operators are not order sensitive.
The Lock and Unlock operators can be used in the standard credit/debit scenarios. For example, let's say that you have a StreamBase application that has two main streams: a credit stream and a debit stream. You must ensure that the credit and debit parts of the application are not working against the same accounts at the same time. You would use Lock operators at the entries into the critical sections of both the credit and debit sections. You would place Unlock operators at the end of the credit and debit critical sections.
The remainder of this topic describes the actions you can take on each tab of the Lock and Unlock operators' Properties views.
Name: Every application component must have a unique name. Use this field to specify or change the component's name. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.
Enable Error Output Port: Check this box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.
Description: Optionally, enter a description to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
The Lock and Unlock Settings tabs allows you to specify the fields and expressions that comprise the lock key, which is used to determine whether tuples can be processed. Tuples matching the lock key cannot be processed until a previous tuple with that same lock key has been unlocked. This tab can only be edited after a valid Lock Set has been connected to the Lock or Unlock operator.
The Dynamic Variables tab allows you to define variables for this operator that can then be used in one of its expressions. A dynamic variable can be updated by any input stream or output stream in your application. For more information, see Using Dynamic Variables.
-
In an operation that performs sorting, any tuple with a null value in the ordering field or in a Boolean expression, will be ignored.
-
If the evaluation of a predicate results in a NullValueException error, the tuple will be dropped.
-
If this component contains a Group Options tab, any null value in a Group By expression will be grouped.
For more information, see Using Nulls.