Mutex Sub-Package

Mutual exclusion locks, or mutexes, are used to ensure serialized access to information in parallel simulations. Such access is necessary when code accesses global variables, shared files, and other elements that might be used by multiple threads concurrently. (See “Mutexes“ on page 420 for a detailed discussion of mutexes.) The Mutex sub-package contains KPs for managing mutexes.

You can create a mutex with op_prg_mt_mutex_create(). This KP lets you specify behavior options, a rank, and a description for the new mutex. Once created, you can lock the mutex with op_prg_mt_mutex_lock(). Code that executes after the op_prg_mt_mutex_lock() call is locked and remains locked until op_prg_mt_mutex_unlock() unlocks the mutex, allowing another thread to access the code. Multiple blocks of code can be wrapped in lock/unlock pairs using the same mutex. This means that at most one of these blocks of code will be executed at any time. When a mutex is no longer needed, destroy it with op_prg_mt_mutex_destroy() to free the associated memory.

A built-in global mutex, with the highest possible rank, is available for times when it is undesirable or impossible to create a specific new mutex. You can use the global mutex by calling op_prg_mt_global_lock() and op_prg_mt_global_unlock().

The op_prg_mt… KPs become no-ops when compiled for sequential execution, because no serialization is needed. The only execution cost is an optional assignment of a success return value to a model variable: op_prg_mt_mutex_create() returns 1 and the other KPs return OPC_COMPCODE_SUCCESS.

Note: Riverbed Modeler provides an additional mutex package (prg_mt…, described in Chapter 6 “Mutex Package” on page 90) for situations where finer control of serialization is needed. However, prg_mt… functions do not provide ODB tracing and do not become no-ops during sequential execution. Thus, you should use the op_prg_mt… KPs whenever possible.