From: Simon Marlow <simonmar@microsoft.com>
Date: Tue, 5 Dec 2006 15:49:27 +0000 (+0000)
Subject: documentation for installHandler
X-Git-Url: http://git.megacz.com/?a=commitdiff_plain;ds=sidebyside;h=a09d886b49d91f9595ec774d6ede487045545f7c;p=haskell-directory.git

documentation for installHandler
merge to 6.6
---

diff --git a/GHC/ConsoleHandler.hs b/GHC/ConsoleHandler.hs
index 7435b92..3c3d2f4 100644
--- a/GHC/ConsoleHandler.hs
+++ b/GHC/ConsoleHandler.hs
@@ -52,6 +52,25 @@ data ConsoleEvent
  | Shutdown
  deriving (Eq, Ord, Enum, Show, Read, Typeable)
 
+-- | Allows Windows console events to be caught and handled.  To
+-- handle a console event, call 'installHandler' passing the
+-- appropriate 'Handler' value.  When the event is received, if the
+-- 'Handler' value is @Catch f@, then a new thread will be spawned by
+-- the system to execute @f e@, where @e@ is the 'ConsoleEvent' that
+-- was received.
+--
+-- Note that console events can only be received by an application
+-- running in a Windows console.  Certain environments that look like consoles
+-- do not support console events, these include:
+--
+--  * Cygwin shells with @CYGWIN=tty@ set (if you don't set @CYGWIN=tty@,
+--    then a Cygwin shell behaves like a Windows console).
+--  * Cygwin xterm and rxvt windows
+--  * MSYS rxvt windows
+--
+-- In order for your application to receive console events, avoid running
+-- it in one of these environments.
+--
 installHandler :: Handler -> IO Handler
 installHandler handler = 
   alloca $ \ p_sp -> do