-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Serialization library for GHC
--
-- This package provides Haskell data serialisation independent of
-- evaluation, by accessing the Haskell heap using foreign primitive
-- operations. Any Haskell data structure apart from mutable data
-- structures (MVars and TVars) can be serialised and
-- later deserialised during the same run, or loaded into a new run, of
-- the same program (the same executable file).
--
-- The library provides operations to serialize Haskell heap
-- data, and to deserialize it:
--
--
-- trySerializeWith :: a -> Int -> IO (Serialized a) -- Int is maximum buffer size to use
-- trySerialize :: a -> IO (Serialized a) -- uses default (maximum) buffer size
-- deserialize :: Serialized a -> IO a
--
--
-- The data type Serialized a is an opaque representation of
-- serialised Haskell data (it contains a ByteArray). A phantom
-- type a ensures type safety within the same program run. Type
-- a can be polymorphic (at compile time, that is) when
-- Serialized a is not used apart from being argument to
-- deserialize. When data are externalised (written to disk or
-- communicated over the network) using the provided instances of
-- Binary or Read and Show, a needs
-- to be monomorphic because they require Typeable context. The
-- instances for Show and Read satisfy read . show
-- == id.
--
-- Packman serialisation is orthogonal to evaluation, heap data
-- are serialised in their current state of evaluation, they might
-- be entirely unevaluated (a thunk) or only partially evaluated
-- (containing thunks). Therefore, there can be cases where a mutable
-- data structure is captured by a thunk, and lead to serialisation
-- failures (typically related to lazy I/O).
--
-- The serialisation routine will throw a PackException if an
-- error occurs inside the C code which accesses the Haskell heap, if a
-- mutable data structure is serialised, or if the serialised data is too
-- large. In presence of concurrent threads, another thread might be
-- evaluating data referred to by the data to be serialised. In
-- this case, the calling thread will block on the ongoing
-- evaluation and continue when evaluated data is available. Internally,
-- there is a PackException P_BLACKHOLE to signal the
-- condition, but it is hidden inside the core library
@package packman
@version 0.5.0
-- | Exception type for packman library, using magic constants #include'd
-- from a C header file shared with the foreign primitive operation code.
--
-- PackExceptions can occur at Haskell level or in the foreign
-- primop.
--
-- All Haskell-level exceptions are cases of invalid data when
-- reading and deserialising Serialised data:
--
--
-- - P_BinaryMismatch: serialised data were produced by a
-- different executable (must be the same binary).
-- - P_TypeMismatch: serialised data have the wrong type
-- - P_ParseError: serialised data could not be parsed (from
-- binary or text format)
--
--
-- The exceptions caused by the foreign primops (return codes) indicate
-- errors at the C level. Most of them can occur when serialising data;
-- the exception is P_GARBLED which indicates that serialised data
-- is garbled.
module GHC.Packing.PackException
-- | Packing exception codes, matching error codes implemented in the
-- runtime system or describing errors which can occur within Haskell.
data PackException
-- | no error, ==0. Internal code, should never be seen by users.
P_SUCCESS :: PackException
-- | RTS: packing hit a blackhole. Used internally, not passed to users.
P_BLACKHOLE :: PackException
-- | RTS: buffer too small
P_NOBUFFER :: PackException
-- | RTS: contains closure which cannot be packed (MVar, TVar)
P_CANNOTPACK :: PackException
-- | RTS: contains unsupported closure type (implementation missing)
P_UNSUPPORTED :: PackException
-- | RTS: impossible case (stack frame, message,...RTS bug!)
P_IMPOSSIBLE :: PackException
-- | RTS: corrupted data for deserialisation
P_GARBLED :: PackException
-- | Haskell: Packet data could not be parsed
P_ParseError :: PackException
-- | Haskell: Executable binaries do not match
P_BinaryMismatch :: PackException
-- | Haskell: Packet data encodes unexpected type
P_TypeMismatch :: PackException
-- | decodes an Int# to a PackException. Magic
-- constants are read from file cbits/Errors.h.
decodeEx :: Int# -> PackException
-- | internal: checks if the given code indicates P_BLACKHOLE
isBHExc :: Int# -> Bool
instance GHC.Classes.Ord GHC.Packing.PackException.PackException
instance GHC.Classes.Eq GHC.Packing.PackException.PackException
instance GHC.Show.Show GHC.Packing.PackException.PackException
instance GHC.Exception.Exception GHC.Packing.PackException.PackException
-- | Serialized type for the packman library, instances and
-- helpers
--
-- The data type Serialized a includes a phantom type
-- a to ensure type safety within one and the same program run.
-- Type a can be polymorphic (at compile time, that is) when
-- Serialized a is not used apart from being argument to
-- deserialize.
--
-- The Show, Read, and Binary instances of
-- Serialized a require an additional Typeable context
-- (which requires a to be monomorphic) in order to implement
-- dynamic type checks when parsing and deserialising data from external
-- sources.
module GHC.Packing.Type
-- | The type of Serialized data. Phantom type a ensures that we
-- unpack data as the expected type.
data Serialized a
Serialized :: ByteArray# -> Serialized a
[packetData] :: Serialized a -> ByteArray#
-- | prints packet as Word array in 4 columns (Word meaning the
-- machine word size), and additionally includes Fingerprint hash values
-- for executable binary and type.
-- | Helper to show a serialized structure as a packet (Word Array)
showWArray :: UArray Int TargetWord -> String
-- | Reads the format generated by the Show instance, checks hash
-- values for executable and type and parses exactly as much as the
-- included data size announces.
-- | Packet Parser, reads the format generated by the Read
-- instance. Could also consume other formats of the array (not
-- implemented). Returns: (data size in words, type fingerprint, array
-- values)
parseP :: ReadS (Int, FP, [TargetWord])
digit :: ReadP Char
colon :: ReadP Char
tabSpace :: ReadP String
newline :: ReadP String
hexNum :: ReadP TargetWord
-- | The binary format of Serialized a data includes
-- FingerPrint hash values for type and executable binary, which are
-- checked when reading Serialized data back in using get.
-- | The module uses a custom GHC fingerprint type with its two Word64
-- fields, to be able to read fingerprints
data FP
FP :: Word64 -> Word64 -> FP
-- | checks whether the type of the given expression matches the given
-- Fingerprint
matches :: Typeable a => a -> FP -> Bool
-- | creates an FP from a GHC Fingerprint
toFP :: Fingerprint -> FP
-- | returns the type fingerprint of an expression
typeFP :: Typeable a => a -> FP
-- | Binary instance for fingerprint data (encoding TypeRep and executable
-- in binary-encoded Serialized a)
-- | To check that the program (executable) is identical when packing and
-- unpacking, the fingerprint type from above is used (Read/Show
-- instances required). An FP fingerprint of the executable is
-- computed once, by unsafePerformIO inside this CAF (safe to inline,
-- just inefficient).
prgHash :: FP
-- | The target word size is the size of a machine word on the platform we
-- run on.
--
-- This type is only used in Binary, Read and Show instances, where
-- packets are stored as UArrays of TargetWord.
--
-- Actually, GHC uses machine word size (as Haskell 2010 spec. does not
-- fix it) so we could just use Word. See
-- http://www.haskell.org/ghc/docs/7.8.3/html/users_guide/bugs-and-infelicities.html#haskell-98-2010-undefined
type TargetWord = Word64
hexWordFmt :: [Char]
instance GHC.Classes.Eq GHC.Packing.Type.FP
instance GHC.Show.Show GHC.Packing.Type.FP
instance GHC.Read.Read GHC.Packing.Type.FP
instance Data.Typeable.Internal.Typeable a => GHC.Show.Show (GHC.Packing.Type.Serialized a)
instance Data.Typeable.Internal.Typeable a => Data.Binary.Class.Binary (GHC.Packing.Type.Serialized a)
instance Data.Binary.Class.Binary GHC.Packing.Type.FP
instance Data.Typeable.Internal.Typeable a => GHC.Read.Read (GHC.Packing.Type.Serialized a)
-- | Wrapper module for the foreign primitive operations
module GHC.Packing.Core
-- | Serialises its argument (in current evaluation state, as a thunk). May
-- block if the argument captures (blackhole'd) data under evaluation,
-- may throw PackExceptions to signal errors. This version uses a
-- default buffer of 10MB (see trySerializeWith for a version with
-- flexible buffer size).
trySerialize :: a -> IO (Serialized a)
-- | Extended serialisation interface: Allocates a buffer of given size (in
-- bytes), serialises data into it, then truncates the buffer to the
-- required size before returning it (as Serialized a)
trySerializeWith :: a -> Int -> IO (Serialized a)
-- | Deserialisation function. May throw PackException
-- P_GARBLED
deserialize :: Serialized a -> IO a
-- | Serialisation of Haskell data structures (independent of
-- evaluation)
--
-- Haskell heap structures can be serialised, capturing their current
-- state of evaluation, and deserialised later during the same program
-- run (effectively duplicating the data). Serialised data can also be
-- written to storage or sent over a network, and deserialised in a
-- different run or different instance of the same executable
-- binary.
--
-- The feature can be used to implement message passing over a network
-- (which is where the runtime support originated), or for various
-- applications based on data persistence, for instance checkpointing and
-- memoisation.
--
-- The library described here supports an operation to serialise Haskell
-- heap data:
--
--
-- trySerialize :: a -> IO (Serialized a)
--
--
-- The routine will throw a PackException if an error occurs
-- inside the C code which accesses the Haskell heap (see
-- PackException). In presence of concurrent threads,
-- another thread might be evaluating data referred to by the data
-- to be serialised. In this case, the calling thread will block
-- on the ongoing evaluation and continue when evaluated data is
-- available. Internally, there is a PackException
-- P_BLACKHOLE to signal the condition, but it is hidden inside
-- the core library (see Background Information below).
--
-- The inverse operation to serialisation is
--
--
-- deserialize :: Serialized a -> IO a
--
--
-- The data type Serialized a includes a phantom type a
-- to ensure type safety within one and the same program run. Type
-- a can be polymorphic (at compile time, that is) when
-- Serialized a is not used apart from being argument to
-- deserialize.
--
-- The Show, Read, and Binary instances of
-- Serialized a require an additional Typeable context
-- (which requires a to be monomorphic) in order to implement
-- dynamic type checks when parsing and deserialising data from external
-- sources. Consequently, the PackException type contains
-- exceptions which indicate parse errors and type/binary mismatch.
module GHC.Packing
-- | Serialises its argument (in current evaluation state, as a thunk). May
-- block if the argument captures (blackhole'd) data under evaluation,
-- may throw PackExceptions to signal errors. This version uses a
-- default buffer of 10MB (see trySerializeWith for a version with
-- flexible buffer size).
trySerialize :: a -> IO (Serialized a)
-- | Extended serialisation interface: Allocates a buffer of given size (in
-- bytes), serialises data into it, then truncates the buffer to the
-- required size before returning it (as Serialized a)
trySerializeWith :: a -> Int -> IO (Serialized a)
-- | Deserialisation function. May throw PackException
-- P_GARBLED
deserialize :: Serialized a -> IO a
-- | The type of Serialized data. Phantom type a ensures that we
-- unpack data as the expected type.
data Serialized a
-- | Packing exception codes, matching error codes implemented in the
-- runtime system or describing errors which can occur within Haskell.
data PackException
-- | no error, ==0. Internal code, should never be seen by users.
P_SUCCESS :: PackException
-- | RTS: packing hit a blackhole. Used internally, not passed to users.
P_BLACKHOLE :: PackException
-- | RTS: buffer too small
P_NOBUFFER :: PackException
-- | RTS: contains closure which cannot be packed (MVar, TVar)
P_CANNOTPACK :: PackException
-- | RTS: contains unsupported closure type (implementation missing)
P_UNSUPPORTED :: PackException
-- | RTS: impossible case (stack frame, message,...RTS bug!)
P_IMPOSSIBLE :: PackException
-- | RTS: corrupted data for deserialisation
P_GARBLED :: PackException
-- | Haskell: Packet data could not be parsed
P_ParseError :: PackException
-- | Haskell: Executable binaries do not match
P_BinaryMismatch :: PackException
-- | Haskell: Packet data encodes unexpected type
P_TypeMismatch :: PackException
-- | Write serialised binary data directly to a file. May throw
-- PackExceptions.
encodeToFile :: Typeable a => FilePath -> a -> IO ()
-- | Directly read binary serialised data from a file. May throw
-- PackExceptions (catches I/O and Binary exceptions from decoding
-- the file and re-throws P_ParseError)
decodeFromFile :: Typeable a => FilePath -> IO a