From 057f5bb2318ea7912d0786bb428bc7e0db2720a9 Mon Sep 17 00:00:00 2001
From: Taylor Otwell <taylorotwell@gmail.com>
Date: Tue, 5 May 2020 09:10:26 -0500
Subject: [PATCH] document session blocking

---
 session.md | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/session.md b/session.md
index f80c0a867f2..dbba1f69924 100644
--- a/session.md
+++ b/session.md
@@ -9,6 +9,7 @@
     - [Flash Data](#flash-data)
     - [Deleting Data](#deleting-data)
     - [Regenerating The Session ID](#regenerating-the-session-id)
+- [Session Blocking](#session-blocking)
 - [Adding Custom Session Drivers](#adding-custom-session-drivers)
     - [Implementing The Driver](#implementing-the-driver)
     - [Registering The Driver](#registering-the-driver)
@@ -198,6 +199,23 @@ Laravel automatically regenerates the session ID during authentication if you ar
 
     $request->session()->regenerate();
 
+<a name="session-blocking"></a>
+## Session Blocking
+
+> {note} To utilize session blocking, your application must be using a cache driver that supports atomic locks. Currently, those cache drivers include the `memcached`, `dynamodb`, `redis`, and `database` cache drivers. In addition, you may not use the `cookie` session driver.
+
+By default, Laravel allows requests using the same session to execute concurrently. So, for example, if you use a JavaScript HTTP library to make two HTTP requests to your application, they will both execute at the same time. For many applications, this is not a problem; however, session data loss can occur in a small subset of applications that make concurrent requests to two different application endpoints which both write data to the session.
+
+To mitigate this, Laravel provides functionality that allows you to limit concurrent requests for a given session. To get started, you may simply chain the `block` method onto your route definition:
+
+    Route::post('/profile', function () {
+        ...
+    })->block($lockSeconds = 10, $waitSeconds = 10)
+
+The `block` method accepts two optional arguments. The first argument accepted by the `block` method is the maximum number of seconds the session lock should be held for before it is released. Of course, if the request finishes executing before this time the lock will be released earlier.
+
+The second argument accepted by the `block` method is the number of seconds a request should wait while attempting to obtain a session lock. A `Illuminate\Contracts\Cache\LockTimoutException` will be thrown if the request is unable to obtain a session lock within the given number of seconds:
+
 <a name="adding-custom-session-drivers"></a>
 ## Adding Custom Session Drivers