[Git][ghc/ghc][wip/document-system-io] Add exception explanation to withFile

[Jade (@Jade)]

Jade pushed to branch wip/document-system-io at Glasgow Haskell Compiler / GHC


Commits:
db782d97 by Jade at 2024-05-08T10:33:32+02:00
Add exception explanation to withFile

- - - - -


1 changed file:

- libraries/ghc-internal/src/GHC/Internal/IO/StdHandles.hs


Changes:

=====================================
libraries/ghc-internal/src/GHC/Internal/IO/StdHandles.hs
=====================================
@@ -90,6 +90,13 @@ openBinaryFile = POSIX.openBinaryFile
 
 -- | The computation @'withFile' path mode action@ opens the file and runs @action@
 -- with the obtained handle before closing the file.
+--
+-- Even when an exception is raised within the 'action', the file will still be closed.
+-- This is why @'withFile' path mode act@ is preferable to
+--
+-- @'openFile' path mode >>= (\\hdl -> act hdl >>= 'System.IO.hClose' hdl)@
+--
+-- See also: 'System.IO.bracket'
 withFile
   :: FilePath         -- ^ The path to the file that should be opened
   -> IOMode           -- ^ The mode in which the file should be opened
@@ -108,6 +115,13 @@ withFile = POSIX.withFile
 -- and runs @action@ with the obtained handle before closing the binary file.
 --
 -- This is different from 'withFile' as in that it does not use any file encoding.
+--
+-- Even when an exception is raised within the 'action', the file will still be closed.
+-- This is why @'withBinaryFile' path mode act@ is preferable to
+--
+-- @'openBinaryFile' path mode >>= (\\hdl -> act hdl >>= 'System.IO.hClose' hdl)@
+--
+-- See also: 'System.IO.bracket'
 withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
 #if defined(mingw32_HOST_OS)
 withBinaryFile = POSIX.withBinaryFile <!> wf



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/db782d979d5db894c37c02bbf69acdae0021ee65

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/db782d979d5db894c37c02bbf69acdae0021ee65
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20240508/55bd4754/attachment-0001.html>