8000 Add docs for the Lock component by jderusse · Pull Request #7364 · symfony/symfony-docs · GitHub
[go: up one dir, main page]

Skip to content

Add docs for the Lock component #7364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Apr 24, 2017
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Fixed minor typos and syntax issues
  • Loading branch information
javiereguiluz authored and jderusse committed Feb 17, 2017
commit d1d3b7126696feb4432af1dbb6c77b066a895c31
29 changes: 11 additions & 18 deletions components/lock.rst
10000
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ infinitely.

To fill this gap, the remote ``Stores`` provide an expirable mechanism: The lock
is acquired for a defined amount of time (named TTL for Time To Live).
When the timeout occured, the lock is automatically released even if the locker
When the timeout occurred, the lock is automatically released even if the locker
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

occurs?

don't call the ``release()`` method.

That's why, when you create a lock on an expirable ``Store``. You have to choose
Expand Down Expand Up @@ -126,13 +126,13 @@ the ``resource`` will stay lock till the timeout.
.. tip::

To avoid letting the Lock in a locking state, try to always release an
expirable lock by wraping the job in a try/catch block for instance.
expirable lock by wrapping the job in a try/catch block for instance.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra blank line here

When you have to work on a really long task, you should not set the TTL to
overlap the duration of this task. Instead, the Lock Component expose a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

exposes

:method:`Symfony\\Component\\Lock\\LockInterface::refresh` method in order to
put off the TTL of the Lock. Thereby you can choose a small initial TTL, and
regulary refresh the lock
regularly refresh the lock
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

missing dot at the end of the sentence.


.. code-block:: php

Expand All @@ -145,7 +145,7 @@ regulary refresh the lock
$lock->acquire();
try {
while (!$finished) {
// perfom a small part of the job.
// perform a small part of the job.

$lock->refresh();
// resource is locked for 30 more seconds.
Expand Down Expand Up @@ -186,10 +186,8 @@ FlockStore
~~~~~~~~~~

The FlockStore use the fileSystem on the local computer to lock and store the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uses

``resource``.
It does not supports expiration, but the lock is automaticaly released when the
PHP process is terminated.

``resource``. It does not supports expiration, but the lock is automatically
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

support

released when the PHP process is terminated.

.. code-block:: php

Expand All @@ -206,7 +204,6 @@ file will be created.
We suggest to use local file, or to use a Store dedicated to remote usage
like Redis or Memcached.


.. _Packagist: https://packagist.org/packages/symfony/lock

.. _lock-store-memcached:
Expand All @@ -221,7 +218,6 @@ The MemcachedStore stores state of ``resource`` in a Memcached server. This

Memcached does not supports TTL lower than 1 seconds.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

support

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 second



It requires to have installed Memcached and have created a connection that
implements the ``\Memcached`` classes::

Expand Down Expand Up @@ -263,7 +259,6 @@ SemaphoreStore

The SemaphoreStore uses the PHP semaphore function to lock a ``resources``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This phrase is confusing "the PHP semaphore function" ... because PHP doesn't have a semaphore() function, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right, I was thinking about PHP semaphore function**s** is it more clear? Or should I rewrite the sentence?



.. code-block:: php

use Symfony\Component\Lock\Store\SemaphoreStore;
Expand All @@ -276,14 +271,14 @@ CombinedStore
~~~~~~~~~~~~~

The CombinedStore synchronize several ``Stores`` together. When it's used to
acquired a Lock, it forward the call to the managed ``Stores``, and regarding the
result, uses a quorum to decide whether or not the lock is acquired.
acquired a Lock, it forwards the call to the managed ``Stores``, and regarding
the result, uses a quorum to decide whether or not the lock is acquired.

.. note::

This ``Store`` is usefull for High availability application. You can provide
This ``Store`` is useful for High availability application. You can provide
several Redis Server, and use theses server to manage the Lock. A
MajorityQuorum is enougth to safely acquire a lock while it allow some Redis
MajorityQuorum is enough to safely acquire a lock while it allow some Redis
server failure.

.. code-block:: php
Expand All @@ -293,7 +288,7 @@ result, uses a quorum to decide whether or not the lock is acquired.
use Symfony\Component\Lock\Store\RedisStore;

$stores = [];
foreach (['server1', 'server2', 'server3'] as $server) {
foreach (array('server1', 'server2', 'server3') as $server) {
$redis= new \Redis();
$redis->connect($server);

Expand All @@ -302,12 +297,10 @@ result, uses a quorum to decide whether or not the lock is acquired.

$store = new CombinedStore($stores, new MajorityQuorum());


.. tip::

You can use the CombinedStore with the UnanimousQuorum to implement chained
``Stores``. It'll allow you to acquire easy local locks before asking for a
remote lock


.. _Packagist: https://packagist.org/packages/symfony/lock
0