Multi-Threading Safety

Riverbed Modeler has a parallel simulation kernel that allows simulations to use multiple processors. To ensure that activities such as the parallel transmission of packets are performed correctly and as quickly as possible, any code involved must use multi-threading-safe APIs (Kernel Procedures and PRG functions).

Note: In this context, multi-threading safety refers to the ability of code to operate safely in a Riverbed parallel-simulation environment. This is not equivalent to operating in user-created threads with an OS thread manager. You cannot call Riverbed functions (KPs or otherwise) from user-created threads.

Riverbed APIs have one of two possible multi-threading safeness levels:

  • MT-safe: These APIs support multi-threading. Multiple threads can execute these APIs in parallel without danger.
  • MT-unsafe: These APIs do not support multi-threading. It is the responsibility of the user to perform appropriate serialization of code that uses MT-unsafe APIs. (Enabling parallelism in these APIs would result in performance loss, rather than the expected gain due to parallelism.)

Most KPs and PRG APIs are MT-safe. Those that are not, or that have some restrictions to their safeness, are identified as such in the API description and are listed in Table 3.

Note: Some packages are not supported by the parallel kernel. If used in a parallel simulation, APIs from such packages will either fail or do nothing.

Table 3: MT-Unsafe KPs and PRG APIs

KP Comment
op_anim_ package Unsafe. Use of animation KPs (especially macro definitions) must be serialized by the user.
op_esys_ package The External System package is not supported by the parallel kernel.
op_ev_count(), op_ev_count_local(), op_ev_next(), op_ev_next_local(), op_ev_pending(), op_ev_seek_time() Safe, but deterministic only for future events (those outside the current execution time window). We recommend not using these KPs in parallel simulations.
op_ima_obj_svar_get() Safe, but must be used with care if multiple clients are accessing or modifying shared svar information.
op_intrpt_priority_get, op_intrpt_priority_set, op_intrpt_priority_set_next KPs related to event priority are not supported by the parallel kernel.
op_prg_list_ sub-package Unsafe. Access to shared lists must be serialized by the user.
op_pro_svar_get() Safe, but must be used with care if multiple clients are accessing or modifying shared svar information.
prg_string_hash_table package Unsafe. Access to shared hash tables must be serialized by the user.
prg_list package Unsafe. Access to shared lists must be serialized by the user.
prg_map package Unsafe. Access to mapped data elements that are shared must be serialized by the user.
prg_vector package Unsafe. Access to shared vectors must be serialized by the user.