Locking Module

In this document, you'll learn about the Locking Module and its providers.

What is the Locking Module?#

The Locking Module manages access to shared resources by multiple processes or threads. It prevents conflicts between processes that are trying to access the same resource at the same time, and ensures data consistency.

Medusa uses the Locking Module to control concurrency, avoid race conditions, and protect parts of code that should not be executed by more than one process at a time. This is especially essential in distributed or multi-threaded environments.

For example, Medusa uses the Locking Module in inventory management to ensure that only one transaction can update the stock levels at a time. By using the Locking Module in this scenario, Medusa prevents overselling an inventory item and keeps its quantity amounts accurate, even during high traffic periods or when receiving concurrent requests.

How to Use the Locking Module?#

You can use the Locking Module as part of the workflows you build for your custom features. A workflow is a special function composed of a series of steps that guarantees data consistency and reliable roll-back mechanism.

In a step of your workflow, you can resolve the Locking Module's service and use its methods to execute an asynchronous job, acquire a lock, or release locks.

For example:

Code
1import { Modules } from "@medusajs/framework/utils"2import { 3  createStep,4  createWorkflow,5} from "@medusajs/framework/workflows-sdk"6
7const step1 = createStep(8  "step-1",9  async ({}, { container }) => {10    const lockingModuleService = container.resolve(11      Modules.LOCKING12    )13    const productModuleService = container.resolve(14      Modules.PRODUCT15    )16
17    await lockingModuleService.execute("prod_123", async () => {18      await productModuleService.deleteProduct("prod_123")19    })20  } 21)22
23export const workflow = createWorkflow(24  "workflow-1",25  () => {26    step1()27  }28)

In the example above, you create a workflow that has a step. In the step, you resolve the services of the Locking and Product modules from the Medusa container.

Then, you use the execute method of the Locking Module to acquire a lock for the product with the ID prod_123 and execute an asynchronous function, which deletes the product.

When to Use the Locking Module?#

You should use the Locking Module when you need to ensure that only one process can access a shared resource at a time. As mentioned in the inventory example previously, you don't want customers to order quantities of inventory that are not available, or to update the stock levels of an item concurrently.

In those scenarios, you can use the Locking Module to acquire a lock for a resource and execute a critical section of code that should not be accessed by multiple processes simultaneously.

What is a Locking Module Provider?#

A Locking Module Provider implements the underlying logic of the Locking Module. It manages the locking mechanisms and ensures that only one process can access a shared resource at a time.

Medusa provides multiple Locking Module Providers that are suitable for development and production. You can also create a custom Locking Module Provider to implement custom locking mechanisms or integrate with third-party services.

Default Locking Module Provider#

By default, Medusa uses the In-Memory Locking Module Provider. This provider uses a plain JavaScript map to store the locks. While this is useful for development, it is not recommended for production environments as it is only intended for use in a single-instance environment.

To add more providers, you can register them in the medusa-config.ts file. For example:

Code
1module.exports = defineConfig({2  // ...3  modules: [4    {5      resolve: "@medusajs/medusa/locking",6      options: {7        providers: [8          // add providers here...9        ]10      }11    }12  ]13})

When you register other providers in medusa-config.ts, Medusa will set the default provider based on the following scenarios:

List of Locking Module Providers#

Medusa provides the following Locking Module Providers. You can use one of them, or Create a Locking Module Provider.