git.iko.soy/streamly
on edf9b36 help sign in
streamly/src/Streamly/FileSystem/Handle.hs
106 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
69 -- ** Write to Handle
70 -- | 'TextEncoding', 'NewLineMode', and 'Buffering' options of the
71 -- underlying handle are ignored. The write occurs from the current seek
72 -- position of the file handle. The write behavior depends on the 'IOMode'
73 -- of the handle.
74 --
75 , write
76 -- , writeUtf8
77 -- , writeUtf8ByLines
78 -- , writeByFrames
79 , writeInChunksOf
80 , writeArrays
82 -- -- * Random Access (Seek)
83 -- -- | Unlike the streaming APIs listed above, these APIs apply to devices or
84 -- files that have random access or seek capability. This type of devices
85 -- include disks, files, memory devices and exclude terminals, pipes,
86 -- sockets and fifos.
87 --
88 -- , readIndex
89 -- XXX we can make the names consistent with the enumerate APIs. For
90 -- example, readFromTo, readFromToUp, readFromToDn, readFrom etc.
91 -- , readSlice
92 -- , readSliceRev
93 -- , readAt -- read from a given position to th end of file
94 -- , readSliceArrayUpto
95 -- , readSliceArrayOf
97 -- , writeIndex
98 -- , writeSlice
99 -- , writeSliceRev
100 -- , writeAt -- start writing at the given position
101 -- , writeSliceArray
102 )
103where
105import Streamly.Internal.FileSystem.Handle
106import Prelude hiding (read)