From 572a0d9a484c43777f6740e4c6f5097fe7e5cb27 Mon Sep 17 00:00:00 2001
From: WouterJ <waldio.webdesign@gmail.com>
Date: Tue, 30 Jul 2013 10:44:05 +0200
Subject: [PATCH] Added docs about immutable dispatcher

---
 .../event_dispatcher/immutable_dispatcher.rst | 41 +++++++++++++++++++
 components/event_dispatcher/index.rst         |  1 +
 components/event_dispatcher/introduction.rst  |  9 ++++
 components/map.rst.inc                        |  1 +
 4 files changed, 52 insertions(+)
 create mode 100644 components/event_dispatcher/immutable_dispatcher.rst

diff --git a/components/event_dispatcher/immutable_dispatcher.rst b/components/event_dispatcher/immutable_dispatcher.rst
new file mode 100644
index 00000000000..c5d17eb6f00
--- /dev/null
+++ b/components/event_dispatcher/immutable_dispatcher.rst
@@ -0,0 +1,41 @@
+.. index::
+    single: Event Dispatcher; Immutable
+
+The Immutable Event Dispatcher
+==============================
+
+.. versionadded:: 2.1
+    This feature was added in Symfony 2.1.
+
+The :class:`Symfony\\Component\\EventDispatcher\\ImmutableEventDispatcher` is
+a locked or frozen event dispatcher. The dispatcher cannot register new
+listeners or subscribers.
+
+The ``ImmutableEventDispatcher`` takes another event dispatcher with all the
+listeners and subscribers. The immutable dispatcher is just a proxy of this
+original dispatcher.
+
+To use it, first create a normal dispatcher (``EventDispatcher`` or
+``ContainerAwareEventDispatcher``) and register some listeners or
+subscribers::
+
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+
+    $dispatcher = new EventDispatcher();
+    $dispatcher->addListener('foo.action', function ($event) {
+        // ...
+    });
+
+    // ...
+
+Now, inject that into an ``ImmutableEventDispatcher``::
+
+    use Symfony\Component\EventDispatcher\ImmutableEventDispatcher;
+    // ...
+
+    $immutableDispatcher = new ImmutableEventDispatcher($dispatcher);
+
+You'll need to use this new dispatcher in your project.
+
+If you are trying to execute one of the methods which modifies the dispatcher
+(e.g. ``addListener``), a ``BadMethodCallException`` is thrown.
diff --git a/components/event_dispatcher/index.rst b/components/event_dispatcher/index.rst
index 4800978d501..9c644faf225 100644
--- a/components/event_dispatcher/index.rst
+++ b/components/event_dispatcher/index.rst
@@ -7,3 +7,4 @@ Event Dispatcher
     introduction
     generic_event
     container_aware_dispatcher
+    immutable_dispatcher
diff --git a/components/event_dispatcher/introduction.rst b/components/event_dispatcher/introduction.rst
index f5087431642..78ea54456c6 100644
--- a/components/event_dispatcher/introduction.rst
+++ b/components/event_dispatcher/introduction.rst
@@ -597,6 +597,15 @@ part of the listener's processing logic::
         }
     }
 
+Other Dispatchers
+-----------------
+
+Besides the commonly used ``EventDispatcher``, the component comes with 2
+other dispatchers:
+
+* :doc:`/components/event_dispatcher/container_aware_dispatcher`
+* :doc:`/components/event_dispatcher/immutable_dispatcher`
+
 .. _Observer: http://en.wikipedia.org/wiki/Observer_pattern
 .. _Closures: http://php.net/manual/en/functions.anonymous.php
 .. _PHP callable: http://www.php.net/manual/en/language.pseudo-types.php#language.types.callback
diff --git a/components/map.rst.inc b/components/map.rst.inc
index 16bcd68ddec..b8060e04860 100644
--- a/components/map.rst.inc
+++ b/components/map.rst.inc
@@ -44,6 +44,7 @@
 
   * :doc:`/components/event_dispatcher/introduction`
   * :doc:`/components/event_dispatcher/container_aware_dispatcher`
+  * :doc:`/components/event_dispatcher/immutable_dispatcher`
   * :doc:`/components/event_dispatcher/generic_event`
 
 * **Filesystem**