===========
      Multicast
     ===========
     
     Point-to-point connections handle a lot of communication needs, but
     passing the same information between many peers becomes challenging as
     the number of direct connections grows.  Sending messages separately
     to each recipient consumes additional processing time and bandwidth,
     which can be a problem for applications such as streaming video or
     audio.  Using *multicast* to deliver messages to more than one
     endpoint at a time achieves better efficiency because the network
     infrastructure ensures that the packets are delivered to all
     recipients.
     
     Multicast messages are always sent using UDP, since TCP requires an
     end-to-end communication channel.  The addresses for multicast, called
     *multicast groups*, are a subset of regular IPv4 address range
     (224.0.0.0 through 230.255.255.255) reserved for multicast traffic.
     These addresses are treated specially by network routers and switches,
     so messages sent to the group can be distributed over the Internet to
     all recipients that have joined the group.
     
     .. note::
     
         Some managed switches and routers have multicast traffic disabled
         by default.  If you have trouble with the example programs, check
         your network hardware settings.
     
     Sending Multicast Messages
     ==========================
     
     This modified echo client will send a message to a multicast group,
     then report all of the responses it receives.  Since it has no way of
     knowing how many responses to expect, it uses a timeout value on the
     socket to avoid blocking indefinitely waiting for an answer.
     
     .. literalinclude:: socket_multicast_sender.py
        :lines: 10-22
     
     The socket also needs to be configured with a *time-to-live* value
     (TTL) for the messages.  The TTL controls how many networks will
     receive the packet.  Set the TTL with the :const:`IP_MULTICAST_TTL`
     option and :func:`setsockopt`.  The default, ``1``, means that the
     packets are not forwarded by the router beyond the current network
     segment.  The value can range up to 255, and should be packed into a
     single byte.
     
     .. literalinclude:: socket_multicast_sender.py
        :lines: 24-27
     
     The rest of the sender looks like the UDP echo client, except that it
     expects multiple responses so uses a loop to call :func:`recvfrom`
     until it times out.
     
     .. literalinclude:: socket_multicast_sender.py
        :lines: 29-
     
     Receiving Multicast Messages
     ============================
     
     The first step to establishing a multicast receiver is to create the
     UDP socket.
     
     .. literalinclude:: socket_multicast_receiver.py
        :lines: 10-21
     
     After the regular socket is created and bound to a port, it can be
     added to the multicast group by using :func:`setsockopt` to change the
     :const:`IP_ADD_MEMBERSHIP` option.  The option value is the 8-byte
     packed representation of the multicast group address followed by the
     network interface on which the server should listen for the traffic,
     identified by its IP address.  In this case, the receiver listens on
     all interfaces using :const:`INADDR_ANY`.
     
     .. literalinclude:: socket_multicast_receiver.py
        :lines: 23-27
     
     The main loop for the receiver is just like the regular UDP echo
     server.
     
     .. literalinclude:: socket_multicast_receiver.py
        :lines: 29-
     
     Example Output
     ==============
     
     This example shows the multicast receiver running on two different
     hosts, ``A`` has address ``192.168.1.17`` and ``B`` has address
     ``192.168.1.8``.
     
     ::
     
         [A]$ python ./socket_multicast_receiver.py  
             
         waiting to receive message
         received 19 bytes from ('192.168.1.17', 51382)
         very important data
         sending acknowledgement to ('192.168.1.17', 51382)
             
         [B]$ python ./socket_multicast_receiver.py 
             
         binding to ('', 10000)
             
         waiting to receive message
         received 19 bytes from ('192.168.1.17', 51382)
         very important data
         sending acknowledgement to ('192.168.1.17', 51382)
     
     The sender is running on host ``A``.
     
     ::
     
         $ python ./socket_multicast_sender.py 
         
         sending "very important data"
         waiting to receive
         received "ack" from ('192.168.1.17', 10000)
         waiting to receive
         received "ack" from ('192.168.1.8', 10000)
         waiting to receive
         timed out, no more responses
         closing socket
     
     The message is sent one time, and two acknowledgements of the outgoing
     message are received, one from each of host ``A`` and ``B``.
     
     .. seealso::
     
         `Wikipedia: Multicast <http://en.wikipedia.org/wiki/Multicast>`__
             Article describing technical details of multicasting.
     
         `Wikipedia: IP Multicast <http://en.wikipedia.org/wiki/IP_multicast>`__
             Article about IP multicasting, with information about addressing.