Add guide on cleaning up state and file resources (#8610)

* WIP

* Add guide

* add changeset

* notebook

* No log in

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

.changeset/smart-rooms-win.md

@@ -0,0 +1,5 @@
+---
+"gradio": patch
+---
+
+fix:Add guide on cleaning up state and file resources

demo/state_cleanup/run.ipynb

@@ -1 +1 @@
-{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: state_cleanup"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["from __future__ import annotations\n", "import gradio as gr\n", "import numpy as np\n", "from PIL import Image\n", "from pathlib import Path\n", "import secrets\n", "import shutil\n", "\n", "current_dir = Path(__file__).parent\n", "\n", "\n", "def generate_random_img(history: list[Image.Image], request: gr.Request):\n", "    \"\"\"Generate a random red, green, blue, orange, yellor or purple image.\"\"\"\n", "    colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 165, 0), (255, 255, 0), (128, 0, 128)]\n", "    color = colors[np.random.randint(0, len(colors))]\n", "    img = Image.new('RGB', (100, 100), color)\n", "    \n", "    user_dir: Path = current_dir / request.username # type: ignore\n", "    user_dir.mkdir(exist_ok=True)\n", "    path = user_dir / f\"{secrets.token_urlsafe(8)}.webp\"\n", "\n", "    img.save(path)\n", "    history.append(img)\n", "\n", "    return img, history, history\n", "\n", "def delete_directory(req: gr.Request):\n", "    if not req.username:\n", "        return\n", "    user_dir: Path = current_dir / req.username\n", "    shutil.rmtree(str(user_dir))\n", "\n", "with gr.Blocks() as demo:\n", "    gr.Markdown(\"\"\"# State Cleanup Demo\n", "                \ud83d\uddbc\ufe0f Images are saved in a user-specific directory and deleted when the users closes the page via demo.unload.\n", "                \"\"\")\n", "    with gr.Row():\n", "        with gr.Column(scale=1):\n", "            with gr.Row():\n", "                img = gr.Image(label=\"Generated Image\", height=300, width=300)\n", "            with gr.Row():\n", "                gen = gr.Button(value=\"Generate\")\n", "            with gr.Row():\n", "                history = gr.Gallery(label=\"Previous Generations\", height=500, columns=10)\n", "                state = gr.State(value=[], delete_callback=lambda v: print(\"STATE DELETED\"))\n", "\n", "    demo.load(generate_random_img, [state], [img, state, history]) \n", "    gen.click(generate_random_img, [state], [img, state, history])\n", "    demo.unload(delete_directory)\n", "\n", "\n", "demo.launch(auth=lambda user,pwd: True,\n", "            auth_message=\"Enter any username and password to continue\")"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}
+{"cells": [{"cell_type": "markdown", "id": "302934307671667531413257853548643485645", "metadata": {}, "source": ["# Gradio Demo: state_cleanup"]}, {"cell_type": "code", "execution_count": null, "id": "272996653310673477252411125948039410165", "metadata": {}, "outputs": [], "source": ["!pip install -q gradio "]}, {"cell_type": "code", "execution_count": null, "id": "288918539441861185822528903084949547379", "metadata": {}, "outputs": [], "source": ["from __future__ import annotations\n", "import gradio as gr\n", "import numpy as np\n", "from PIL import Image\n", "from pathlib import Path\n", "import secrets\n", "import shutil\n", "\n", "current_dir = Path(__file__).parent\n", "\n", "\n", "def generate_random_img(history: list[Image.Image], request: gr.Request):\n", "    \"\"\"Generate a random red, green, blue, orange, yellor or purple image.\"\"\"\n", "    colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 165, 0), (255, 255, 0), (128, 0, 128)]\n", "    color = colors[np.random.randint(0, len(colors))]\n", "    img = Image.new('RGB', (100, 100), color)\n", "\n", "    user_dir: Path = current_dir / request.session_hash\n", "    user_dir.mkdir(exist_ok=True)\n", "    path = user_dir / f\"{secrets.token_urlsafe(8)}.webp\"\n", "\n", "    img.save(path)\n", "    history.append(img)\n", "\n", "    return img, history, history\n", "\n", "def delete_directory(req: gr.Request):\n", "    if not req.username:\n", "        return\n", "    user_dir: Path = current_dir / req.username\n", "    shutil.rmtree(str(user_dir))\n", "\n", "with gr.Blocks(delete_cache=(60, 3600)) as demo:\n", "    gr.Markdown(\"\"\"# State Cleanup Demo\n", "                \ud83d\uddbc\ufe0f Images are saved in a user-specific directory and deleted when the users closes the page via demo.unload.\n", "                \"\"\")\n", "    with gr.Row():\n", "        with gr.Column(scale=1):\n", "            with gr.Row():\n", "                img = gr.Image(label=\"Generated Image\", height=300, width=300)\n", "            with gr.Row():\n", "                gen = gr.Button(value=\"Generate\")\n", "            with gr.Row():\n", "                history = gr.Gallery(label=\"Previous Generations\", height=500, columns=10)\n", "                state = gr.State(value=[], delete_callback=lambda v: print(\"STATE DELETED\"))\n", "\n", "    demo.load(generate_random_img, [state], [img, state, history])\n", "    gen.click(generate_random_img, [state], [img, state, history])\n", "    demo.unload(delete_directory)\n", "\n", "\n", "demo.launch()"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}

demo/state_cleanup/run.py

@@ -14,8 +14,8 @@ def generate_random_img(history: list[Image.Image], request: gr.Request):
     colors = [(255, 0, 0), (0, 255, 0), (0, 0, 255), (255, 165, 0), (255, 255, 0), (128, 0, 128)]
     color = colors[np.random.randint(0, len(colors))]
     img = Image.new('RGB', (100, 100), color)
-    
-    user_dir: Path = current_dir / request.username # type: ignore
+
+    user_dir: Path = current_dir / request.session_hash
     user_dir.mkdir(exist_ok=True)
     path = user_dir / f"{secrets.token_urlsafe(8)}.webp"
 
@@ -30,7 +30,7 @@ def delete_directory(req: gr.Request):
     user_dir: Path = current_dir / req.username
     shutil.rmtree(str(user_dir))
 
-with gr.Blocks() as demo:
+with gr.Blocks(delete_cache=(60, 3600)) as demo:
     gr.Markdown("""# State Cleanup Demo
                 🖼️ Images are saved in a user-specific directory and deleted when the users closes the page via demo.unload.
                 """)
@@ -44,10 +44,9 @@ def delete_directory(req: gr.Request):
                 history = gr.Gallery(label="Previous Generations", height=500, columns=10)
                 state = gr.State(value=[], delete_callback=lambda v: print("STATE DELETED"))
 
-    demo.load(generate_random_img, [state], [img, state, history]) 
+    demo.load(generate_random_img, [state], [img, state, history])
     gen.click(generate_random_img, [state], [img, state, history])
     demo.unload(delete_directory)
 
 
-demo.launch(auth=lambda user,pwd: True,
-            auth_message="Enter any username and password to continue")
+demo.launch()

gradio/blocks.py

@@ -131,7 +131,7 @@ def __init__(
         self.temp_files: set[str] = set()
         self.GRADIO_CACHE = get_upload_folder()
         self.key = key
-        # Keep tracks of files that should not be deleted when the delete_cache parmaeter is set
+        # Keep tracks of files that should not be deleted when the delete_cache parmameter is set
         # These files are the default value of the component and files that are used in examples
         self.keep_in_cache = set()
 

gradio/components/state.py

@@ -18,6 +18,7 @@ class State(Component):
     """
     Special hidden component that stores session state across runs of the demo by the
     same user. The value of the State variable is cleared when the user refreshes the page.
+    The state state is stored on the server for 60 minutes after the user closes the tab.
     Demos: interface_state, blocks_simple_squares, state_cleanup
     Guides: real-time-speech-recognition
     """

guides/03_additional-features/07_resource-cleanup.md

@@ -0,0 +1,48 @@
+# Resource Cleanup
+
+Your Gradio application may create resources during its lifetime.
+Examples of resources are `gr.State` variables, any variables you create and explicitly hold in memory, or files you save to disk. 
+Over time, these resources can use up all of your server's RAM or disk space and crash your application.
+
+Gradio provides some tools for you to clean up the resources created by your app:
+
+1. Automatic deletion of `gr.State` variables.
+2. Automatic cache cleanup with the `delete_cache` parameter.
+2. The `Blocks.unload` event.
+
+Let's take a look at each of them individually.
+
+## Automatic deletion of `gr.State`
+
+When a user closes their browser tab, Gradio will automatically delete any `gr.State` variables associated with that user session after 60 minutes. If the user connects again within those 60 minutes, no state will be deleted.
+
+You can control the deletion behavior further with the following two parameters of `gr.State`:
+
+1. `delete_callback` - An arbitrary function that will be called when the variable is deleted. This function must take the state value as input. This function is useful for deleting variables from GPU memory.
+2. `time_to_live` - The number of seconds the state should be stored for after it is created or updated. This will delete variables before the session is closed, so it's useful for clearing state for potentially long running sessions.
+
+## Automatic cache cleanup via `delete_cache`
+
+Your Gradio application will save uploaded and generated files to a special directory called the cache directory. Gradio uses a hashing scheme to ensure that duplicate files are not saved to the cache but over time the size of the cache will grow (especially if your app goes viral 😉).
+
+Gradio can periodically clean up the cache for you if you specify the `delete_cache` parameter of `gr.Blocks()`, `gr.Interface()`, or `gr.ChatInterface()`. 
+This parameter is a tuple of the form `[frequency, age]` both expressed in number of seconds.
+Every `frequency` seconds, the temporary files created by this Blocks instance will be deleted if more than `age` seconds have passed since the file was created. 
+For example, setting this to (86400, 86400) will delete temporary files every day if they are older than a day old.
+Additionally, the cache will be deleted entirely when the server restarts.
+
+## The `unload` event
+
+Additionally, Gradio now includes a `Blocks.unload()` event, allowing you to run arbitrary cleanup functions when users disconnect (this does not have a 60 minute delay).
+Unlike other gradio events, this event does not accept inputs or outptus.
+You can think of the `unload` event as the opposite of the `load` event.
+
+## Putting it all together
+
+The following demo uses all of these features. When a user visits the page, a special unique directory is created for that user.
+As the user interacts with the app, images are saved to disk in that special directory.
+When the user closes the page, the images created in that session are deleted via the `unload` event.
+The state and files in the cache are cleaned up automatically as well.
+
+$code_state_cleanup
+$demo_state_cleanup