stdio-0.2.0.0: A simple and high performance IO toolkit for Haskell

Copyright(c) Dong Han 2017~2019
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellNone
LanguageHaskell2010

Std.IO.FileSystemT

Contents

Description

This module provide IO operations related to filesystem, operations are implemented using libuv's threadpool to achieve non-block behavior (non-block here meaning won't block other haskell threads), which should be prefered when the operations' estimated time is long enough(>1ms) or running with a non-threaded haskell runtime, such as accessing network filesystem or scan a very large directory. Otherwise you may block RTS's capability thus all the other haskell threads live on it.

The threadpool version operations have overheads similar to safe FFI, but provide same adventages:

  • The libuv's threadpool have a limit on concurrent threads number (4 by default), which can reduce disk contention.
  • The threadpool version works with non-threaded runtime, which doesn't have safe FFI available.
  • The threadpool version won't relinquish current HEC (Haskell Execution Context) a.k.a. capability.
Synopsis

regular file devices

data UVFile Source #

UVFile wrap a uv_file_t and a referencing counter

Note this is a differet data type from Std.IO.FileSystem 's one, the Input and Output instance use thread pool version functions.

libuv implements read and write method with both implict and explict offset capability. (negative offset result in read/write system call otherwise pread/pwrite), we provide implict offset interface with UVFile, which is NOT thread safe.

An offset bundled UVFileReader, UVFileWriter is also provided, which can be used concurrently. The offset is protected with MVar and increasing automatically.

Instances
Show UVFile Source # 
Instance details

Defined in Std.IO.FileSystemT

Output UVFile Source # 
Instance details

Defined in Std.IO.FileSystemT

Methods

writeOutput :: UVFile -> Ptr Word8 -> Int -> IO () Source #

Input UVFile Source # 
Instance details

Defined in Std.IO.FileSystemT

Methods

readInput :: UVFile -> Ptr Word8 -> Int -> IO Int Source #

data UVFileReader Source #

Instances
Input UVFileReader Source # 
Instance details

Defined in Std.IO.FileSystemT

newUVFileReader Source #

Arguments

:: UVFile

the file we're reading

-> Int64

initial reading offset

-> IO UVFileReader 

Create a reader from an UVFile.

Note this will not increase UVFile's referencing counter.

peekUVFileReader Source #

Arguments

:: UVFileReader 
-> Int64

the new offset

-> IO Int64

the old offset

Change reader's offset.

data UVFileWriter Source #

Instances
Output UVFileWriter Source # 
Instance details

Defined in Std.IO.FileSystemT

Methods

writeOutput :: UVFileWriter -> Ptr Word8 -> Int -> IO () Source #

newUVFileWriter Source #

Arguments

:: UVFile

the file we're writing

-> Int64

initial writing offset

-> IO UVFileWriter 

Create a writer from an UVFile.

Note this will not increase UVFile's referencing counter.

peekUVFileWriter Source #

Arguments

:: UVFileWriter 
-> Int64

the new offset

-> IO Int64

the old offset

Change writer's offset.

initUVFile Source #

Arguments

:: HasCallStack 
=> CBytes 
-> UVFileFlag

Opening flags, e.g. O_CREAT .|. O_RDWR

-> UVFileMode

Sets the file mode (permission and sticky bits), but only if the file was created, see DEFAULT_MODE.

-> Resource UVFile 

init a file Resource, which open a file when used.

Resource closing will wait for the referencing counter goes down to zero (no reading or writing is in process), which can be a problem if you are using multiple readers or writers in multiple threads. In that case you have to stop all reading or writing thread if you don't want to block the resource thread.

opening constant

data UVFileMode where Source #

Bundled Patterns

pattern DEFAULT_MODE :: UVFileMode

Default mode for open, 0o666(readable and writable).

pattern S_IRWXU :: UVFileMode

00700 user (file owner) has read, write and execute permission

pattern S_IRUSR :: UVFileMode

00400 user has read permission

pattern S_IWUSR :: UVFileMode

00200 user has write permission

pattern S_IXUSR :: UVFileMode

00100 user has execute permission

pattern S_IRWXG :: UVFileMode

00070 group has read, write and execute permission

pattern S_IRGRP :: UVFileMode

00040 group has read permission

pattern S_IWGRP :: UVFileMode

00020 group has write permission

pattern S_IXGRP :: UVFileMode

00010 group has execute permission

pattern S_IRWXO :: UVFileMode

00007 others have read, write and execute permission

pattern S_IROTH :: UVFileMode

00004 others have read permission

Instances
Eq UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Num UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Storable UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Bits UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

FiniteBits UVFileMode Source # 
Instance details

Defined in Std.IO.UV.FFI

data UVFileFlag where Source #

Bundled Patterns

pattern O_APPEND :: UVFileFlag

The file is opened in append mode. Before each write, the file offset is positioned at the end of the file.

pattern O_CREAT :: UVFileFlag

The file is created if it does not already exist.

pattern O_DIRECT :: UVFileFlag

File IO is done directly to and from user-space buffers, which must be aligned. Buffer size and address should be a multiple of the physical sector size of the block device, (DO NOT USE WITH stdio's BufferedIO)

pattern O_DSYNC :: UVFileFlag

The file is opened for synchronous IO. Write operations will complete once all data and a minimum of metadata are flushed to disk.

Note o_DSYNC is supported on Windows via FILE_FLAG_WRITE_THROUGH.

pattern O_EXCL :: UVFileFlag

If the o_CREAT flag is set and the file already exists, fail the open.

Note In general, the behavior of o_EXCL is undefined if it is used without o_CREAT. There is one exception: on Linux 2.6 and later, o_EXCL can be used without o_CREAT if pathname refers to a block device. If the block device is in use by the system (e.g., mounted), the open will fail with the error EBUSY.

pattern O_EXLOCK :: UVFileFlag

Atomically obtain an exclusive lock.

Note UV_FS_O_EXLOCK is only supported on macOS and Windows. (libuv: Changed in version 1.17.0: support is added for Windows.)

pattern O_NOATIME :: UVFileFlag

Do not update the file access time when the file is read.

Note o_NOATIME is not supported on Windows.

pattern O_NOFOLLOW :: UVFileFlag

If the path is a symbolic link, fail the open.

Note o_NOFOLLOW is not supported on Windows.

pattern O_RDONLY :: UVFileFlag

Open the file for read-only access.

pattern O_RDWR :: UVFileFlag

Open the file for read-write access.

pattern O_SYMLINK :: UVFileFlag

Open the symbolic link itself rather than the resource it points to.

pattern O_SYNC :: UVFileFlag

The file is opened for synchronous IO. Write operations will complete once all data and all metadata are flushed to disk.

Note o_SYNC is supported on Windows via FILE_FLAG_WRITE_THROUGH.

pattern O_TRUNC :: UVFileFlag

If the file exists and is a regular file, and the file is opened successfully for write access, its length shall be truncated to zero.

pattern O_WRONLY :: UVFileFlag

Open the file for write-only access.

pattern O_RANDOM :: UVFileFlag

Access is intended to be random. The system can use this as a hint to optimize file caching.

Note o_RANDOM is only supported on Windows via FILE_FLAG_RANDOM_ACCESS.

pattern O_SHORT_LIVED :: UVFileFlag

The file is temporary and should not be flushed to disk if possible.

Note o_SHORT_LIVED is only supported on Windows via FILE_ATTRIBUTE_TEMPORARY.

pattern O_SEQUENTIAL :: UVFileFlag

Access is intended to be sequential from beginning to end. The system can use this as a hint to optimize file caching.

Note o_SEQUENTIAL is only supported on Windows via FILE_FLAG_SEQUENTIAL_SCAN.

pattern O_TEMPORARY :: UVFileFlag

The file is temporary and should not be flushed to disk if possible.

Note o_TEMPORARY is only supported on Windows via FILE_ATTRIBUTE_TEMPORARY.

Instances
Eq UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Num UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Storable UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Bits UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

FiniteBits UVFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

filesystem operations

mkdir :: HasCallStack => CBytes -> UVFileMode -> IO () Source #

Equivalent to mkdir(2).

Note mode is currently not implemented on Windows.

unlink :: HasCallStack => CBytes -> IO () Source #

Equivalent to unlink(2).

mkdtemp :: HasCallStack => CBytes -> IO CBytes Source #

Equivalent to http://linux.die.net/man/3/mkdtemp

Creates a temporary directory in the most secure manner possible. There are no race conditions in the directory’s creation. The directory is readable, writable, and searchable only by the creating user ID. The user of mkdtemp() is responsible for deleting the temporary directory and its contents when done with it.

Note: the argument is the prefix of the temporary directory, so no need to add XXXXXX ending.

rmdir :: HasCallStack => CBytes -> IO () Source #

Equivalent to rmdir(2).

data DirEntType Source #

Instances
Eq DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

Read DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

Show DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

Generic DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

Associated Types

type Rep DirEntType :: Type -> Type #

type Rep DirEntType Source # 
Instance details

Defined in Std.IO.UV.FFI

type Rep DirEntType = D1 (MetaData "DirEntType" "Std.IO.UV.FFI" "stdio-0.2.0.0-5YmH16k3vlO7FAtmF9PgfB" False) (((C1 (MetaCons "DirEntUnknown" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "DirEntFile" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "DirEntDir" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "DirEntLink" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "DirEntFIFO" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "DirEntSocket" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "DirEntChar" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "DirEntBlock" PrefixI False) (U1 :: Type -> Type))))

scandir :: HasCallStack => CBytes -> IO [(CBytes, DirEntType)] Source #

Equivalent to scandir(3).

Note Unlike scandir(3), this function does not return the “.” and “..” entries.

Note On Linux, getting the type of an entry is only supported by some file systems (btrfs, ext2, ext3 and ext4 at the time of this writing), check the getdents(2) man page.

data UVStat Source #

Instances
Eq UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

Methods

(==) :: UVStat -> UVStat -> Bool #

(/=) :: UVStat -> UVStat -> Bool #

Ord UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

Generic UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

Associated Types

type Rep UVStat :: Type -> Type #

Methods

from :: UVStat -> Rep UVStat x #

to :: Rep UVStat x -> UVStat #

type Rep UVStat Source # 
Instance details

Defined in Std.IO.UV.FFI

type Rep UVStat = D1 (MetaData "UVStat" "Std.IO.UV.FFI" "stdio-0.2.0.0-5YmH16k3vlO7FAtmF9PgfB" False) (C1 (MetaCons "UVStat" PrefixI True) ((((S1 (MetaSel (Just "stDev") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stMode") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64)) :*: (S1 (MetaSel (Just "stNlink") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stUid") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64))) :*: ((S1 (MetaSel (Just "stGid") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stRdev") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64)) :*: (S1 (MetaSel (Just "stIno") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stSize") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64)))) :*: (((S1 (MetaSel (Just "stBlksize") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stBlocks") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64)) :*: (S1 (MetaSel (Just "stFlags") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64) :*: S1 (MetaSel (Just "stGen") SourceUnpack SourceStrict DecidedStrict) (Rec0 Word64))) :*: ((S1 (MetaSel (Just "stAtim") SourceUnpack SourceStrict DecidedStrict) (Rec0 UVTimeSpec) :*: S1 (MetaSel (Just "stMtim") SourceUnpack SourceStrict DecidedStrict) (Rec0 UVTimeSpec)) :*: (S1 (MetaSel (Just "stCtim") SourceUnpack SourceStrict DecidedStrict) (Rec0 UVTimeSpec) :*: S1 (MetaSel (Just "stBirthtim") SourceUnpack SourceStrict DecidedStrict) (Rec0 UVTimeSpec))))))

data UVTimeSpec Source #

Constructors

UVTimeSpec 
Instances
Eq UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

Generic UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

Associated Types

type Rep UVTimeSpec :: Type -> Type #

Storable UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

type Rep UVTimeSpec Source # 
Instance details

Defined in Std.IO.UV.FFI

type Rep UVTimeSpec = D1 (MetaData "UVTimeSpec" "Std.IO.UV.FFI" "stdio-0.2.0.0-5YmH16k3vlO7FAtmF9PgfB" False) (C1 (MetaCons "UVTimeSpec" PrefixI True) (S1 (MetaSel (Just "uvtSecond") SourceUnpack SourceStrict DecidedStrict) (Rec0 CLong) :*: S1 (MetaSel (Just "uvtNanoSecond") SourceUnpack SourceStrict DecidedStrict) (Rec0 CLong)))

rename :: HasCallStack => CBytes -> CBytes -> IO () Source #

Equivalent to rename(2).

Note On Windows if this function fails with UV_EBUSY, UV_EPERM or UV_EACCES, it will retry to rename the file up to four times with 250ms wait between attempts before giving up. If both path and new_path are existing directories this function will work only if target directory is empty.

fsync :: HasCallStack => UVFile -> IO () Source #

Equivalent to fsync(2).

fdatasync :: HasCallStack => UVFile -> IO () Source #

Equivalent to fdatasync(2).

ftruncate :: HasCallStack => UVFile -> Int64 -> IO () Source #

Equivalent to ftruncate(2).

data UVCopyFileFlag where Source #

Flags control copying.

  • COPYFILE_EXCL: If present, uv_fs_copyfile() will fail with UV_EEXIST if the destination path already exists. The default behavior is to overwrite the destination if it exists.
  • COPYFILE_FICLONE: If present, uv_fs_copyfile() will attempt to create a copy-on-write reflink. If the underlying platform does not support copy-on-write, then a fallback copy mechanism is used.

Bundled Patterns

pattern COPYFILE_DEFAULT :: UVCopyFileFlag 
pattern COPYFILE_EXCL :: UVCopyFileFlag 
pattern COPYFILE_FICLONE :: UVCopyFileFlag 
Instances
Eq UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Num UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Storable UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Bits UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

FiniteBits UVCopyFileFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

copyfile :: HasCallStack => CBytes -> CBytes -> UVCopyFileFlag -> IO () Source #

Copies a file from path to new_path.

Warning: If the destination path is created, but an error occurs while copying the data, then the destination path is removed. There is a brief window of time between closing and removing the file where another process could access the file.

data UVAccessMode where Source #

Bundled Patterns

pattern F_OK :: UVAccessMode 
pattern R_OK :: UVAccessMode 
pattern W_OK :: UVAccessMode 
pattern X_OK :: UVAccessMode 
Instances
Eq UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Num UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Storable UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

Bits UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

FiniteBits UVAccessMode Source # 
Instance details

Defined in Std.IO.UV.FFI

access :: HasCallStack => CBytes -> UVAccessMode -> IO AccessResult Source #

Equivalent to access(2) on Unix. Windows uses GetFileAttributesW().

chmod :: HasCallStack => CBytes -> UVFileMode -> IO () Source #

Equivalent to chmod(2).

fchmod :: HasCallStack => UVFile -> UVFileMode -> IO () Source #

Equivalent to fchmod(2).

utime Source #

Arguments

:: HasCallStack 
=> CBytes 
-> Double

atime, i.e. access time

-> Double

mtime, i.e. modify time

-> IO () 

Equivalent to utime(2).

libuv choose Double type due to cross platform concerns, we only provide micro-second precision:

  • second = v
  • nanosecond = (v * 1000000) % 1000000 * 1000;

second and nanosecond are fields in UVTimeSpec respectively.

Note libuv prior to v1.23.1 have issues which may result in nanosecond not set, futime doesn't have

futime :: HasCallStack => UVFile -> Double -> Double -> IO () Source #

Equivalent to futime(2).

Same precision notes with utime.

data UVSymlinkFlag where Source #

Bundled Patterns

pattern SYMLINK_DEFAULT :: UVSymlinkFlag 
pattern SYMLINK_DIR :: UVSymlinkFlag 
pattern SYMLINK_JUNCTION :: UVSymlinkFlag 
Instances
Eq UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Num UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Ord UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Read UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Show UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Storable UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

Bits UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

FiniteBits UVSymlinkFlag Source # 
Instance details

Defined in Std.IO.UV.FFI

link :: HasCallStack => CBytes -> CBytes -> IO () Source #

Equivalent to link(2).

symlink :: HasCallStack => CBytes -> CBytes -> UVSymlinkFlag -> IO () Source #

Equivalent to symlink(2).

| Note On Windows the flags parameter can be specified to control how the symlink will be created.

On other platforms these flags are ignored.

realpath :: HasCallStack => CBytes -> IO CBytes Source #

Equivalent to realpath(3) on Unix. Windows uses GetFinalPathNameByHandle.

Warning This function has certain platform-specific caveats that were discovered when used in Node.

  • macOS and other BSDs: this function will fail with UV_ELOOP if more than 32 symlinks are found while resolving the given path. This limit is hardcoded and cannot be sidestepped.
  • Windows: while this function works in the common case, there are a number of corner cases where it doesn’t:

    • Paths in ramdisk volumes created by tools which sidestep the Volume Manager (such as ImDisk) cannot be resolved.
    • Inconsistent casing when using drive letters.
    • Resolved path bypasses subst’d drives.

While this function can still be used, it’s not recommended if scenarios such as the above need to be supported. The background story and some more details on these issues can be checked here.

Note This function is not implemented on Windows XP and Windows Server 2003. On these systems, UV_ENOSYS is returned.