Important
The Lock and Unlock operators and the Lock Set data construct are deprecated and will be removed in a future release. Do not design new applications that use this feature. Contact StreamBase Technical Support if you need help with replacing this feature in an existing application.
This topic explains how the Lock and Unlock operators and the Lock Set data construct are used together, and describes 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.
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 diagram. (There are exceptions to this general rule, as explained in Execution Order and Concurrency.) You may need to use Lock and Unlock operators and a Lock Set data construct 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. 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 data types as the fields defined in the schemas used in the
Lock Sets. For example, if the Lock Set has two 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, respectively.
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 are applied against the fields in the tuples. The expressions generate a value, X. Only one tuple that corresponds to the value X is allowed past the Lock operators at any one time. All other tuples that evaluate to X are buffered. Tuples that evaluate to values other than X are 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 is 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 is released from the paired Lock operator in FIFO order into the critical section of the application.
Take care 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 may become unstable as the buffer in the Lock operator grows, using up available memory.
The Lock Set schema is likely to be different, compared to the schemas of the input streams entering the Lock and Unlock operators. For example, the input stream schemas may have five fields, but you only want to lock and unlock on one of those fields. Therefore, the Lock Set schema will have only 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 top port 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 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 portions of the application are not working against the same accounts at the same time. You would use Lock operators at the entry points into the critical sections of both the credit and debit sections. 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: Use this field to specify or change the component's name, which must be unique in the application. 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: Select this check 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 text 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.
Use the Lock Settings tab (and the Unlock Settings tab in the Unlock operator) to specify the fields and expressions that comprise the lock key, which is used to determine whether tuples can be passed downstream for processing. 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 operator.