[commit: base] master: Add some commentary in GHC.Event.Manager to the explain the poll loop. (ab22fa5)

[Johan Tibell]

Repository : ssh://darcs.haskell.org//srv/darcs/packages/base

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/ab22fa531ddd35c504f780c8fcfab34dcdf37804

>---------------------------------------------------------------

commit ab22fa531ddd35c504f780c8fcfab34dcdf37804
Author: Andreas Voellmy <andreas.voellmy at gmail.com>
Date:   Mon Jan 7 20:04:36 2013 -0500

    Add some commentary in GHC.Event.Manager to the explain the poll loop.

>---------------------------------------------------------------

 GHC/Event/Manager.hs |    8 ++++++++
 1 files changed, 8 insertions(+), 0 deletions(-)

diff --git a/GHC/Event/Manager.hs b/GHC/Event/Manager.hs
index 5c0ac0a..8fc42e5 100644
--- a/GHC/Event/Manager.hs
+++ b/GHC/Event/Manager.hs
@@ -246,6 +246,14 @@ loop mgr at EventManager{..} = do
             Releasing -> putMVar emLock ()
             _         -> cleanup mgr
 
+-- | To make a step, we first do a non-blocking poll, in case
+-- there are already events ready to handle. This improves performance
+-- because we can make an unsafe foreign C call, thereby avoiding
+-- forcing the current Task to release the Capability and forcing a context switch.
+-- If the poll fails to find events, we yield, putting the poll loop thread at
+-- end of the Haskell run queue. When it comes back around, we do one more
+-- non-blocking poll, in case we get lucky and have ready events.
+-- If that also returns no events, then we do a blocking poll.
 step :: EventManager -> IO State
 step mgr at EventManager{..} = do
   waitForIO