Added docs about immutable dispatcher

Author: wouterj

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.

components/event_dispatcher/index.rst

@@ -7,3 +7,4 @@ Event Dispatcher
     introduction
     generic_event
     container_aware_dispatcher
+    immutable_dispatcher

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

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**