| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Quantum.Random.Store
Contents
Description
This module provides functionality for quantum random data operations involving the local data store and/or the settings file.
It also provides a way to coordinate access to these local files.
See AccessControl for details. Any IO operation that uses these files can used in a
coordinated way by wrapping them in a withAccess.
Some of these functions already come in special access-controlled variants because they only
require access in particular branches or phases of execution.
In particular we have addSafely, extractSafely and observeSafely.
Finally, there is functionality to ensure that a forked thread is allowed to finish, in case
main would otherwise return too soon. This is primarily needed to provide addConcurrently,
but it can be re-used by forking a thread with forkSafely and exiting the program with
exitSafely.
Usually to be imported via the Quantum.Random module.
- getStoreFile :: IO FilePath
- getStore :: IO ByteString
- getStoreBytes :: IO [Word8]
- storeSize :: IO Int
- save :: String -> IO ()
- status :: IO ()
- putStore :: ByteString -> IO ()
- putStoreBytes :: [Word8] -> IO ()
- appendToStore :: ByteString -> IO ()
- addToStore :: Int -> IO ()
- addSafely :: AccessControl -> Int -> IO ()
- addConcurrently :: AccessControl -> Int -> IO ThreadId
- fill :: IO ()
- refill :: IO ()
- load :: String -> IO ()
- clearStore :: IO ()
- extract :: Int -> IO [Word8]
- extractSafely :: AccessControl -> Int -> IO [Word8]
- observe :: Maybe DisplayStyle -> Int -> IO ()
- observeSafely :: AccessControl -> Maybe DisplayStyle -> Int -> IO ()
- peek :: Maybe DisplayStyle -> Int -> IO ()
- peekAll :: Maybe DisplayStyle -> IO ()
- display_ :: Maybe DisplayStyle -> [Word8] -> IO ()
- getMinStoreSize :: IO Int
- getTargetStoreSize :: IO Int
- getDefaultStyle :: IO DisplayStyle
- setMinStoreSize :: Int -> IO ()
- setTargetStoreSize :: Int -> IO ()
- setDefaultStyle :: DisplayStyle -> IO ()
- restoreDefaults :: IO ()
- reinitialize :: IO ()
- data AccessControl
- initAccessControl :: IO AccessControl
- withAccess :: AccessControl -> IO a -> IO a
- forkSafely :: AccessControl -> IO () -> IO ThreadId
- exitSafely :: AccessControl -> IO ()
Data store operations
Basic store access
getStoreFile :: IO FilePath Source #
Get path of local store file set up by cabal on installation.
getStore :: IO ByteString Source #
Retrieve quantum random data from local store as a raw bytestring.
getStoreBytes :: IO [Word8] Source #
Retrieve quantum random data from local store as a list of bytes.
save :: String -> IO () Source #
Save the data store to another file, specified by the provided path. Asks for overwrite confirmation if the file already exists.
Display status information: Current store size, minimum size setting, target size setting, default display style and data file path.
Store update
putStore :: ByteString -> IO () Source #
Insert data into local store as a raw bytestring, overwriting any current contents.
putStoreBytes :: [Word8] -> IO () Source #
Insert data into local store as a list of bytes, overwriting any current contents.
appendToStore :: ByteString -> IO () Source #
Append the supplied bytestring to the store file.
addToStore :: Int -> IO () Source #
Retrieve the specified number of QRN bytes and add them to the store.
addSafely :: AccessControl -> Int -> IO () Source #
Like addToStore, but uses AccessControl to ensure that file writing doesn't interfere with
other operations.
addConcurrently :: AccessControl -> Int -> IO ThreadId Source #
Fork a thread to add data to the store concurrently.
Calculate the amount of data needed to reach target store size and retrieve it from ANU.
load :: String -> IO () Source #
Load binary data from specified file path, append it to the data store.
clearStore :: IO () Source #
Remove all data from the store.
Primary store access
extract :: Int -> IO [Word8] Source #
Get the specified number of QRN bytes, either from the store and/or by obtaining more from ANU as needed. As the name implies, the obtained bytes are removed from the store. If the store is left with fewer than the minimum number of QRN bytes it is filled back to the target size.
extractSafely :: AccessControl -> Int -> IO [Word8] Source #
Access-controlled version of extract.
Store data display
observeSafely :: AccessControl -> Maybe DisplayStyle -> Int -> IO () Source #
Destructively view the specified number of bytes, via extractSafely.
Access-controlled version of observe.
peek :: Maybe DisplayStyle -> Int -> IO () Source #
Non-destructively view the specified number of bytes.
display_ :: Maybe DisplayStyle -> [Word8] -> IO () Source #
Like display only taking a Maybe DisplayStyle as the first argument, where Nothing
signifies using the default display style.
Settings file operations
Settings access
getMinStoreSize :: IO Int Source #
Query the settings file for the minimum store size setting.
getTargetStoreSize :: IO Int Source #
Query the settings file for the target store size setting.
getDefaultStyle :: IO DisplayStyle Source #
Query the settings file for the default display style.
Settings update
setMinStoreSize :: Int -> IO () Source #
Update the minimum store size setting in the settings file.
setTargetStoreSize :: Int -> IO () Source #
Update the target store size setting in the settings file.
setDefaultStyle :: DisplayStyle -> IO () Source #
Update the default DisplayStyle setting in the settings file.
restoreDefaults :: IO () Source #
Restore default settings.
reinitialize :: IO () Source #
Restore default settings and refill the store.
Store access control
data AccessControl Source #
A data type to coordinate access to the local files, implemented with an MVar (). When the
unit is present, access is available. IO operations that need access to the store or settings
file remove it from the MVar before doing so, and then replace it when they're done. Then
whenever two such operations might otherwise interfere, they will instead wait their turn to
obtain the access. This functionality is implemented with initAccessControl and withAccess.
Secondarily, it also contains another MVar () used to prevent premature program exit when
a forked thread is running, implemented as forkSafely and exitSafely. The qrand
executable uses this to ensure that a concurrent operation to add data from ANU can finish.
initAccessControl :: IO AccessControl Source #
Initiate the access control system.
withAccess :: AccessControl -> IO a -> IO a Source #
Perform the supplied IO action only when access is granted.
forkSafely :: AccessControl -> IO () -> IO ThreadId Source #
Perform the supplied IO action in a new thread while preventing premature program exit
in conjunction with exitSafely.
exitSafely :: AccessControl -> IO () Source #
Exit with this operation to ensure a thread forked with forkSafely can finish before
main returns.