git.iko.soy/streamly
on ab6587b help sign in
streamly/src/Streamly/FileSystem/Handle.hs
107 lines 4.0 kB history raw
1{-# LANGUAGE CPP #-}
2{-# LANGUAGE BangPatterns #-}
3{-# LANGUAGE MagicHash #-}
4{-# LANGUAGE RecordWildCards #-}
5{-# LANGUAGE UnboxedTuples #-}
7#include "inline.hs"
9-- |
10-- Module : Streamly.FileSystem.Handle
11-- Copyright : (c) 2018 Composewell Technologies
12--
13-- License : BSD3
14-- Maintainer : streamly@composewell.com
15-- Stability : experimental
16-- Portability : GHC
17--
18-- Read and write streams and arrays to and from file handles. File handle IO
19-- APIs are quite similar to "Streamly.Memory.Array" read write APIs. In that
20-- regard, arrays can be considered as in-memory files or files can be
21-- considered as on-disk arrays.
22--
23-- Control over file reading and writing behavior in terms of buffering,
24-- encoding, decoding is in the hands of the programmer, the 'TextEncoding',
25-- 'NewLineMode', and 'Buffering' options of the underlying handle provided by
26-- GHC are not needed and ignored.
27--
28-- > import qualified Streamly.FileSystem.Handle as FH
29--
31-- IO APIs are divided into two categories, sequential streaming IO APIs and
32-- random access IO APIs.
34module Streamly.FileSystem.Handle
35 (
36 -- * Sequential/Streaming IO
37 -- | Stream data to or from a file or device sequentially. When reading,
38 -- the stream is lazy and generated on-demand as the consumer consumes it.
39 -- Read IO requests to the IO device are performed in chunks limited to a
40 -- maximum size of 32KiB, this is referred to as @defaultChunkSize@ in the
41 -- documentation. One IO request may or may not read the full
42 -- chunk. If the whole stream is not consumed, it is possible that we may
43 -- read slightly more from the IO device than what the consumer needed.
44 -- Unless specified otherwise in the API, writes are collected into chunks
45 -- of @defaultChunkSize@ before they are written to the IO device.
47 -- Streaming APIs work for all kind of devices, seekable or non-seekable;
48 -- including disks, files, memory devices, terminals, pipes, sockets and
49 -- fifos. While random access APIs work only for files or devices that have
50 -- random access or seek capability for example disks, memory devices.
51 -- Devices like terminals, pipes, sockets and fifos do not have random
52 -- access capability.
54 -- ** Read From Handle
55 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
56 -- underlying handle are ignored. The read occurs from the current seek
57 -- position of the file handle. The stream ends as soon as EOF is
58 -- encountered.
60 -- XXX once we have APIs to read any type 'a' the array stream
61 -- reading/writing APIs can be expressed in terms of the polymorphic API.
62 read
63 -- , readUtf8
64 -- , readLines
65 -- , readFrames
66 , readInChunksOf
67 , readArraysOf
68 , readArrays
70 -- ** Write to Handle
71 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
72 -- underlying handle are ignored. The write occurs from the current seek
73 -- position of the file handle. The write behavior depends on the 'IOMode'
74 -- of the handle.
75 --
76 , write
77 -- , writeUtf8
78 -- , writeUtf8ByLines
79 -- , writeByFrames
80 , writeInChunksOf
81 , writeArrays
83 -- -- * Random Access (Seek)
84 -- -- | Unlike the streaming APIs listed above, these APIs apply to devices or
85 -- files that have random access or seek capability. This type of devices
86 -- include disks, files, memory devices and exclude terminals, pipes,
87 -- sockets and fifos.
88 --
89 -- , readIndex
90 -- XXX we can make the names consistent with the enumerate APIs. For
91 -- example, readFromTo, readFromToUp, readFromToDn, readFrom etc.
92 -- , readSlice
93 -- , readSliceRev
94 -- , readAt -- read from a given position to th end of file
95 -- , readSliceArrayUpto
96 -- , readSliceArrayOf
98 -- , writeIndex
99 -- , writeSlice
100 -- , writeSliceRev
101 -- , writeAt -- start writing at the given position
102 -- , writeSliceArray
103 )
104where
106import Streamly.Internal.FileSystem.Handle
107import Prelude hiding (read)