LockableTrait Documentation Lacks Clarity on Multi-Server Limitations

[yariksheptykin]

Description

The documentation for LockableTrait does not clearly mention its limitations regarding available locking backends and its unsuitability for multi-server environments. This can lead to developers (like me) unknowingly using it in scenarios where it won't work as expected, potentially causing issues with concurrent execution.

The documentation should explicitly state that LockableTrait is primarily designed for single-server (or shared filesystem) scenarios.

See also symfony/symfony#35535

What do you think?

Example

However, it's important to note that LockableTrait has certain limitations:

• Limited to single-server environments: LockableTrait relies on internal lock storage that is not shared across servers. This means it is not suitable for distributed locking needed in multi-server setups.
• Limited customization: While LockableTrait simplifies locking for basic scenarios, it restricts customization options. It uses internally created stores and factories, preventing the use of custom lock factories or integration with external lock stores like Redis.

For multi-server environments or scenarios requiring more control and customization, we recommend using the LockFactory component directly. Refer to the Lock component documentation for the guidance.

[n0rbyt3]

You:

The documentation should explicitly state that LockableTrait is primarily designed for single-server (or shared filesystem) scenarios.

The documentation:

You can use locks to prevent the same command from running multiple times on the same server.

symfony/symfony#35535 (comment):

The trait instantiates the lock store and the lock factory internally to hide the usage of the lock component in an easy-to-use API for commands. But that means it can only use stores which require no dependency.

As soon as you want to use a lock factory injected through dependency injection [...], the trait is useless. All the remaining logic is already encapsulated in the lock component itself: https://symfony.com/doc/master/components/lock.html#usage

And making the trait itself support injecting a factory inside it would make it more complex.

There is nothing to add IMO.

[yariksheptykin]

Thanks @n0rbyt3 for highlighting that bit.

It was not clear to me that sentence refers to LockableTrait. From the way this page is written this is not obvious (at least to me).

The page starts with a general discussion about locks, linking to wikipedia. This reads as if it is related to locks in general. Stating that locks (in general) can only be used to lock commands running "on the same server" is not true. With the Lock component we indeed can lock commands in distributed systems as well.

What is truly limited to single-server applications is the LockableTrait. This is done intentionally by design, which is understandable. But I suggest that we highlight this limitation in the very same paragraph where we introduce the the LockableTrait.

To me the page as a whole should be build up like this:

• Short introduction to locks in general
• LockableTrait as easy but limited option for locking commands on a single server
• Reference to Lock component for more complex use-cases

What do you think about it?

[carsonbot]

Thank you for this issue.
There has not been a lot of activity here for a while. Has this been resolved?

[stof]

This should be discussed in the issue tracker of the documentation, to be seen by the documentation team

And even better, you could do a PR to improve the documentation.

[yariksheptykin]

I will be happy to open a PR if you agree that the docs need improvement on this particular section. @n0rbyt3 did not seem convinced. It seems like I am the only one finding that part confusing. If this is so we can leave the docs as the are.

[wadjeroudi]

from sf 7.1, you can directly customize the lockFactory on the trait, you should close it.