@@ -67,14 +67,14 @@ allowInterrupt :: IO ()
6767allowInterrupt = unblock $ return ()
6868#endif
6969
70−-- | Run an 'Application' on the given port. This calls 'runSettings' with
71−-- 'defaultSettings'.
70+-- | Run an 'Application' on the given port.
71+-- This calls 'runSettings' with 'defaultSettings'.
7272run :: Port -> Application -> IO ()
7373run p = runSettings defaultSettings { settingsPort = p }
7474
75−-- | Run an 'Application' on the port present in the @PORT@ environment variable
76−--
77−-- Uses the 'Port' given when the variable is unset.
75+-- | Run an 'Application' on the port present in the @PORT@
76+-- environment variable. Uses the 'Port' given when the variable is unset.
77+-- This calls 'runSettings' with 'defaultSettings'.
7878--
7979-- Since 3.0.9
8080runEnv :: Port -> Application -> IO ()
@@ -90,6 +90,8 @@ runEnv p app = do
9090 _ -> fail $ "Invalid value in $PORT: " ++ sp
9191
9292-- | Run an 'Application' with the given 'Settings'.
93+-- This opens a listen socket on the port defined in 'Settings' and
94+-- calls 'runSettingsSocket'.
9395runSettings :: Settings -> Application -> IO ()
9496runSettings set app = withSocketsDo $
9597 bracket
@@ -99,15 +101,17 @@ runSettings set app = withSocketsDo $
99101 setSocketCloseOnExec socket
100102 runSettingsSocket set socket app)
101103
102−-- | Same as 'runSettings', but uses a user-supplied socket instead of opening
103−-- one. This allows the user to provide, for example, Unix named socket, which
104+-- | This installs a shutdown handler for the given socket and
105+-- calls 'runSettingsConnection' with the default connection setup action
106+-- which handles plain (non-cipher) HTTP.
107+-- When the listen socket in the second argument is closed, all live
108+-- connections are gracefully shut down.
109+--
110+-- The supplied socket can be a Unix named socket, which
104111-- can be used when reverse HTTP proxying into your application.
105112--
106113-- Note that the 'settingsPort' will still be passed to 'Application's via the
107114-- 'serverPort' record.
108−--
109−-- When the listen socket in the second argument is closed, all live
110−-- connections are gracefully shut down.
111115runSettingsSocket :: Settings -> Socket -> Application -> IO ()
112116runSettingsSocket set socket app = do
113117 settingsInstallShutdownHandler set closeListenSocket
@@ -125,10 +129,13 @@ runSettingsSocket set socket app = do
125129
126130 closeListenSocket = sClose socket
127131
128−-- | Allows you to provide a function which will return a 'Connection'. In
129−-- cases where creating the @Connection@ can be expensive, this allows the
130−-- expensive computations to be performed in a separate thread instead of the
131−-- main server loop.
132+-- | The connection setup action would be expensive. An good example
133+-- is initialization of TLS.
134+-- So, this convers the connection setup action to the connection maker
135+-- which will be executed after forking a new worker thread.
136+-- Then this calles 'runSettingsConnectionMaker' with the connection maker.
137+-- This allows the expensive computations to be performed
138+-- in a separate worker thread instead of the main server loop.
132139--
133140-- Since 1.3.5
134141runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()
@@ -138,6 +145,8 @@ runSettingsConnection set getConn app = runSettingsConnectionMaker set getConnMa
138145 (conn, sa) <- getConn
139146 return (return conn, sa)
140147
148+-- | This modifies the connection maker so that it returns 'TCP' for 'Transport'
149+-- (i.e. plain HTTP) then calls 'runSettingsConnectionMakerSecure'.
141150runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()
142151runSettingsConnectionMaker x y =
143152 runSettingsConnectionMakerSecure x (go y)
@@ -146,8 +155,10 @@ runSettingsConnectionMaker x y =
146155
147156----------------------------------------------------------------
148157
149−-- | Allows you to provide a function which will return a function
150−-- which will return 'Connection'.
158+-- | The core run function which takes 'Settings',
159+-- a connection maker and 'Application'.
160+-- The connection maker can return a connection of either plain HTTP
161+-- or HTTP over TLS.
151162--
152163-- Since 2.1.4
153164runSettingsConnectionMakerSecure :: Settings -> IO (IO (Connection, Transport), SockAddr) -> Application -> IO ()