MUTEX_ACQUIRE

This activity acquires an exclusive lock using a specified identifier.  It can be used (in conjunction with the MUTEX_RELEASE activity) to implement "single-threaded" access to a specified "resource", or, to put it another way, to block concurrent usage of the "resource".

For example, you may need to invoke a third-party provided web service that requires authentication, but permits only one concurrent request.  If you need to implement this web service in your BPI solutions, then the MUTEX_ACQUIRE and MUTEX_RELEASE activities can be used (surrounding the web-service call) to ensure that only one active process attempts to invoke the web service, while any other concurrent process attempting to do so either waits or treats the unavailability as an exception accordingly.

If the activity is unable to acquire the requested exclusive lock using the specified identifier, it will end with an error.  If your Processing Sequence does not explicitly CATCH and handle the error, then the Processing Sequence will end in error too, but can (usually) be restarted from the point of failure.

If your solution attempts to acquire a lock using the same identifier more than once in the same processing sequence run (without releasing it in the meantime), the second and subsequent attempts succeed, but have no functional effect – there is no "counter" associated with the lock, so you do not have to release it the same number of times as you acquired it.

When implementing MUTEX_ACQUIRE, the possibility arises of unanticipated circumstances leading to affected processes being unexpectedly "blocked" from normal operation.  You need to understand this and plan procedures to free locks that inadvertently remain. In the simplest instance you can immediately free a lock by running the MUTEX_RELEASE activity - if you wish, you can do this directly from the LANSA Composer client (it does not have to be included in a processing sequence, but can be run on its own).  In these circumstances, you will normally need to specify *YES for the FORCERELEASE parameter.

Important notes:

1.  You should use the MUTEX_ACQUIRE activity judiciously and sparingly.  Excessive use of this activity may make the very act of acquiring and releasing locks a bottleneck in your solution that proves, itself, to be an impediment to normal processing sequence throughput.

2.  When implementing the MUTEX_ACQUIRE activity, we advise that you always "pair" it with a corresponding MUTEX_RELEASE activity surrounding the Processing Sequence directives and activities (as closely as possible) that comprise the conceptual resource you are seeking to protect.  Options are available for automatic release of the locks - refer to the description of the DURATION parameter – but we advise that you do not rely on these exclusively, but include the MUTEX_RELEASE activity as early as possible to explicitly free the lock.

3.  If you are familiar with the concept of object locking in the IBM i operating system, you should not make the mistake of assuming that the MUTEX_ACQUIRE activity behaves in the same way.  Locks obtained using MUTEX_ACQUIRE are represented by record(s) in LANSA Composer's internal database and will NOT be relinquished by ending a job, a subsystem or even the system.

LANSA Composer supplies the example Processing Sequence EXAMPLE_MUTEX01 as a simple illustration of the use of this activity.  Refer to Example Processing Sequences for information on installing and using the example Processing Sequences.  Refer to the notes attached to the EXAMPLE_MUTEX01 Processing Sequence for information on using the example.

INPUT Parameters:

LOCKID: Required

This parameter must specify the identifier for the exclusive lock to be acquired.  A maximum of 32 characters may be used for the identifier.  If successful, the lock will block any other process that attempts to acquire a lock using the same identifier.

The identifier you use with MUTEX_ACQUIRE (and MUTEX_RELEASE) is a purely conceptual identifier – it does not represent any "real" system object or resource.  However, it is your responsibility to devise and use an appropriate naming convention that will prevent unintended contention arising from using the same identifier for different purposes or resources.

DURATION: Optional

This parameter can specify the duration of the acquired lock, such that LANSA Composer may free the lock automatically where appropriate.  If it is not specified, a default of *AUTOACTIVE is assumed.  You can choose from the following supported values:

*AUTOACTIVE	This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity OR until the current processing sequence run ends, whether it completes normally or not. This option has the advantage of minimizing the risk of inadvertently leaving locks that may block subsequent processes. However, you may choose to avoid this option if you anticipate that your processing sequence may end in error while the lock is active and you wish the process to be restartable from that point.  When you restart the processing sequence run that ended in error, it will no longer have the lock.  You need to consider whether this behavior is appropriate for your solution.
*AUTOCOMPLETE	This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity OR until the current processing sequence run ends normally or in a state that is ineligible to be restarted. If your processing sequence ends in error, but remains eligible to be restarted, the lock is NOT automatically released. This option ensures that the processing sequence run, when restarted, still has the specified lock.  However, it will block other processing sequences until this one has been restarted and run to normal completion.
*INDEFINITE	This value specifies that the lock will endure until explicitly released using the MUTEX_RELEASE activity. LANSA Composer will NOT automatically release the lock under any circumstances.  It is your responsibility to ensure the lock is released at the appropriate time using the MUTEX_RELEASE activity.

 

RETRIES: Optional

If the activity cannot immediately acquire the specified lock, this parameter (along with the RETRYINTERVAL parameter) determines whether and how the activity will wait and retry the request.

The activity will try again to acquire the lock as many times as specified by this parameter.

The default value is 3, meaning that the activity will retry three times (total of four attempts).  If the lock still cannot be acquired after the specified number of retries, then the activity will end in error.

You may specify zero, if you want the activity to end in error immediately after the first and only attempt to acquire the lock.

RETRYINTERVAL: Optional

If the activity cannot immediately acquire the specified lock, and a value greater than zero is specified (or assumed) for the RETRIES parameter, this parameter specifies how long (in milliseconds) the activity will wait between retry attempts.

The default value is 500, meaning that the activity will wait for approximately half a second to elapse before retrying.

OUTPUT Parameters:

There are no output parameters