From e2f121bf74eba9697698dc86696dd8a1ef21c03b Mon Sep 17 00:00:00 2001
From: youkaichao <youkaichao@gmail.com>
Date: Sat, 23 Mar 2024 18:22:11 -0700
Subject: [PATCH] Update index.rst to improve the demo usage (#314)

---
 docs/index.rst | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 5fb5fb6..1a7d72a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -49,6 +49,7 @@ working directory is currently used. To do so, create a :class:`FileLock <filelo
 
 .. code-block:: python
 
+    import os
     from filelock import Timeout, FileLock
 
     file_path = "high_ground.txt"
@@ -62,16 +63,19 @@ locks:
 .. code-block:: python
 
     with lock:
-        with open(file_path, "a") as f:
-            f.write("Hello there!")
+        if not os.path.exists(file_path):
+            with open(file_path, "w") as f:
+                f.write("Hello there!")
+    # here, all processes can see consistent content in the file
 
     lock.acquire()
     try:
-        with open(file_path, "a") as f:
-            f.write("General Kenobi!")
+        if not os.path.exists(file_path):
+            with open(file_path, "w") as f:
+                f.write("General Kenobi!")
     finally:
         lock.release()
-
+    # here, all processes can see consistent content in the file
 
     @lock
     def decorated():
@@ -80,6 +84,11 @@ locks:
 
     decorated()
 
+Note: When a process gets the lock (i.e. within the `with lock:` region), it is usually good to check what has
+already been done by other processes. For example, each process above first check the existence of the file. If
+it is already created, we should not destroy the work of other processes. This is typically the case when we want
+just one process to write content into a file, and let every process to read the content.
+
 The :meth:`acquire <filelock.BaseFileLock.acquire>` method accepts also a ``timeout`` parameter. If the lock cannot be
 acquired within ``timeout`` seconds, a :class:`Timeout <filelock.Timeout>` exception is raised: