Creating Locks
Locks prevent simultaneous execution of specific processes; there are three types of locks, simple (the process that holds the lock runs exclusively), counted ( <n> processes can hold the lock and run simultaneously), and sharedExclusive (locks have a count, defaulting to 1, allowing no more than one process to run concurrently. A process that has gained hold of one or more counts of a sharedExclusive lock will only ever release them again once it has reached a final status. When two or more processes have the same sharedExclusive lock and one of them has reached status Running, has left too few lock counts for the others to start, will prevent the other jobs waiting on the lock from starting until it has reached a final status. When multiple processes wait for a lock, all processes are re-scheduled once the lock is released and one or more of then get hold of the lock, depending on the available lock type, the number of available slots in the counted lock or the number of counts consumed by the job(s) that managed to get hold of the sharedExclusive lock, while the others are re-scheduled to LockWait.
Locks are part of the Definitions section in the navigation bar.
Simple Locks
Simple locks are exclusive, only one process can hold a lock at any given time.
Counted Locks
Counted locks allow you specify how many processes can hold the same lock simultaneously. The lock has a specific number of counts that can be held by processes. Each process that uses the lock attempts to get hold of a specific number of lock counts; if it succeeds it starts running and keeps hold of the lock counts until it reaches a final status. Note that if the value on the process definition exceeds the value on the lock, the process will never run.
Example 1: A lock has 40 lock counts and three processes are about to attempt to get hold of the lock. Process A requires 5 lock counts, B requires 30, and C``10. Process A gets hold of 5 lock counts, B gets hold of 30, and C is set to status LockWait as too few lock counts are available; it has to wait for either A or B to reach a final state before it can attempt to get hold of the lock again. By the time B reaches a final state, process A is still running, processes D and E (both requiring 15 lock counts each) are waiting with C for the lock. The system treats all 3 requests sequentially, all three are rescheduled as soon as B releases the lock counts, these are then distributed on a first come, first served basis.
Example 2: A lock has 40 lock counts, process A is holding 15, so 25 are available. Process B is scheduled and requires 26 lock counts, it is set to LockWait. Processes C is scheduled and requires 10 lock counts, it is set to LockWait since processes B is in LockWait and was the first of the two to request the lock ( first come, first served ). Processes B and C will start simultaneously as soon as A has released the lock.
sharedExclusive Locks
This type is similar to the counted lock feature. The lock has either a specific number of lock counts or an unlimited number. Processes request either a shared or an exclusive hold on the lock. A shared hold always equates to holding 1 lock count and an exclusive hold equates to holding all lock counts.
Lock Contention
Locks are typically used when you want to prevent two processes of a single process definition from running simultaneously. It is not recommended to use locks to restrict the number of concurrent processes, use queue limits in this case. When a lock is freed, all processes waiting for this lock will be rescheduled and the first process to get hold of the lock will force all other processes attempting to get the lock to be rescheduled again, this can have consequences on performance when many processes are waiting on a lock. If you are planning on having many processes wait on a lock, use queue limits instead. You can specify a default queue for a process definition and set the execution size of the queue to a low number - with a great number of processes, this will considerably increase performance.
Context-Menu
Locks support the following context-menu actions:
| Action | Description |
|---|---|
| Edit Security | Edit the security of the lock |
| Duplicate | Make a copy of the lock to create a similar one |
| Delete | Delete the lock |
| Export > Export | Export the lock into a CAR file |
| Export > Export with related objects | Export the lock into a CAR file including referenced objects |
| Promote > Promote to system | Promote the object to a remote system |
| Promote > Edit further then promote | Edit the export rule set prior to promoting |
| Promote | Promote the lock to another Redwood Server instance |
| Edit | Edit the lock |
| Expand All | Expand all locks in the current filter |
| Show permalinks | Show links that can be used from third party applications to link to the object |
| Add to navigation bar | Add the current object to the navigation bar |
| New lock | Create a new lock |
| Filter > New Filter | Create a new lock filter |
| Filter > Edit Filter | Edit current lock filter |
| Filter > Delete | Delete current lock filter |
| Filter > Duplicate Filter | Create a copy of the filter |
| Filter > Export Filter | Export the filter into a CAR file |
| Filter > Add to navigation bar | Add the filter to a navigation bar |
| Filter > Create filter from search | Create a filter from the current IntelliSearch query |
Finding Locks
You can search for locks using filters and the Search Locks box on the Locks tab. This box is known as the IntelliSearch box and located under your username on the top right-hand side of the user interface. Filters allow you to specify a list of objects with static criteria. IntelliSearch allows you to specify complex queries in a simple way using prefixes. Prefixes are used to specify which property you are searching in and have short as well as long syntaxes. For example, if you want to display all locks with the term import in the comment, you would use the search criteria as follows:
c:import
You can search more than one property, as follows:
c:import n:Bi
note
No spaces should be entered before or after the colon (: ).
See the Advanced Object Search for more information.
The following table illustrates the available prefixes for locks:
| Prefixes | Description |
|---|---|
| n, name | searches the name property |
| c, comm, comment | searches the documentation property |
| d, desc, description | searches the description property |
| a, application | searches the application property |
| cb, changedbefore | (internal) search for locks that changed before a certain ISO-8601 period |
Security
| Privilege | Description |
|---|---|
| Lock.Create | Create locks |
| Lock.Delete | Delete locks |
| Lock.Edit | Edit locks |
| Lock.View | Access locks |
You can grant privileges on two levels, Access and Admin; a privilege granted on Admin level allows the grantee to grant the privilege to other users. These privileges can be granted per partition or system-wide.
The Security tab allows you to specify which users can access, edit, and delete the lock.
Procedure
Creating a Lock
- Choose "Definitions > Locks".
- Choose New Lock to create a lock.
- Fill in the details, refer to the section below.
- Choose Save and Close to save the lock.
Lock
- Name - The name of the lock.
- Application - The name of the application used to group this object.
- Description - An optional description of the lock.
- Documentation - An optional comment of the lock.
Assigning a lock to a Process Definition
Example
Choose "Definitions > Locks" in the Navigation bar. Choose the New Lock button and fill in these values:
Lock
Name: DataWareHouseLoadRun
Description: Data Warehouse load is running
Documentation: The data warehouse is being loaded. For data warehouse consistency, this process cannot be run concurrently.