-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A checksummed variation on Twitter's Snowflake UID generation algorithm -- -- See the file ./README.md, which is included in the package and also on -- GitHub. @package snowchecked @version 0.0.2.0 -- | This module is internal, subject to breaking changes without a major -- version increment, and therefore should only be imported by -- Data.Snowchecked. module Data.Snowchecked.Types -- | The state of a given generated instance. Note that the actual value is -- calculated on demand. data Flake Flake :: Word256 -> Word256 -> Word256 -> SnowcheckedConfig -> Flake -- | The bit-truncated time [flakeTime] :: Flake -> Word256 -- | The bit-truncated count [flakeCount] :: Flake -> Word256 -- | The bit-truncated node id [flakeNodeId] :: Flake -> Word256 -- | The configuration used to create the flake. [flakeConfig] :: Flake -> SnowcheckedConfig -- | The state that needs to be communicated between flake generation -- calls. This should be treated as opaque by consumers of this library: -- messing about with its internals may cause your code to hang -- indefinitely. newtype SnowcheckedGen SnowcheckedGen :: MVar Flake -> SnowcheckedGen [genLastFlake] :: SnowcheckedGen -> MVar Flake -- | Configuration that specifies how many bits are used for each part of -- the id. These values are not validated and may be any legal value for -- the type. -- -- The default value provided by def is 64 bits in total length, -- just like the original Snowflake algorithm. -- -- Note that specifying 0 check bits results in the normal Snowflake -- generation. Setting confTimeBits or confCountBits near -- zero will significantly limit the total number of UIDs that can be -- generated, as well as the throughput of the UID generation. data SnowcheckedConfig SnowcheckedConfig :: Word8 -> Word8 -> Word8 -> Word8 -> SnowcheckedConfig -- | Number of bits used to hold the time [confTimeBits] :: SnowcheckedConfig -> Word8 -- | Number of bits used to count instances per-time [confCountBits] :: SnowcheckedConfig -> Word8 -- | Number of bits derived from the node id [confNodeBits] :: SnowcheckedConfig -> Word8 -- | Number of bits used to store the checksum [confCheckBits] :: SnowcheckedConfig -> Word8 instance GHC.Classes.Ord Data.Snowchecked.Types.SnowcheckedConfig instance GHC.Generics.Generic Data.Snowchecked.Types.SnowcheckedConfig instance GHC.Show.Show Data.Snowchecked.Types.SnowcheckedConfig instance GHC.Classes.Eq Data.Snowchecked.Types.SnowcheckedConfig instance GHC.Generics.Generic Data.Snowchecked.Types.Flake instance GHC.Classes.Ord Data.Snowchecked.Types.Flake instance GHC.Show.Show Data.Snowchecked.Types.Flake instance GHC.Classes.Eq Data.Snowchecked.Types.Flake instance Control.DeepSeq.NFData Data.Snowchecked.Types.Flake instance Control.DeepSeq.NFData Data.Snowchecked.Types.SnowcheckedConfig instance Data.Default.Class.Default Data.Snowchecked.Types.SnowcheckedConfig module Data.Snowchecked.Internal.Import cutBits :: (Num a, Bits a) => a -> Int -> a cutShiftBits :: (Num a, Bits a) => a -> Int -> Int -> a shiftCutBits :: (Num a, Bits a) => a -> Int -> Int -> a toInt :: Integral a => a -> Int toWord8 :: Integral a => a -> Word8 toWord32 :: Integral a => a -> Word32 -- | The Bits class defines bitwise operations over integral types. -- -- class Eq a => Bits a -- | Bitwise "and" (.&.) :: Bits a => a -> a -> a -- | Bitwise "or" (.|.) :: Bits a => a -> a -> a -- | Shift the argument left by the specified number of bits (which must be -- non-negative). Some instances may throw an Overflow exception -- if given a negative input. -- -- An instance can define either this and shiftR or the unified -- shift, depending on which is more convenient for the type in -- question. shiftL :: Bits a => a -> Int -> a -- | Shift the first argument right by the specified number of bits. The -- result is undefined for negative shift amounts and shift amounts -- greater or equal to the bitSize. Some instances may throw an -- Overflow exception if given a negative input. -- -- Right shifts perform sign extension on signed number types; i.e. they -- fill the top bits with 1 if the x is negative and with 0 -- otherwise. -- -- An instance can define either this and shiftL or the unified -- shift, depending on which is more convenient for the type in -- question. shiftR :: Bits a => a -> Int -> a infixl 8 `shiftR` infixl 8 `shiftL` infixl 7 .&. infixl 5 .|. module Data.Snowchecked.Encoding.Class -- | The class of things that can be generated from and to a Flake. class IsFlake a fromFlake :: IsFlake a => Flake -> a parseFlake :: (IsFlake a, MonadFail m) => SnowcheckedConfig -> a -> m Flake parseFish :: (IsFlake a, MonadFail m) => SnowcheckedConfig -> a -> m Flakeish -- | Something that might be a Flake. The fields might not be -- truncated to the appropriate size. data Flakeish Flakeish :: Word256 -> Word256 -> Word256 -> Word256 -> Flakeish [fishNodeId] :: Flakeish -> Word256 [fishCount] :: Flakeish -> Word256 [fishTime] :: Flakeish -> Word256 [fishCheck] :: Flakeish -> Word256 -- | Is this Flakeish valid under the given SnowcheckedConfig -- settings? goodFish :: SnowcheckedConfig -> Flakeish -> Bool -- | This module provides a generalized conversion function between a -- Flake and all members of the typeclass Integral. It is -- specialized for the Integer, Word32, and Word64 -- types. It is marked as incoherent due to the constraint being no -- smaller than the instance type, so it is undecidable. module Data.Snowchecked.Encoding.Integral instance GHC.Real.Integral a => Data.Snowchecked.Encoding.Class.IsFlake a -- | module Data.Snowchecked.Encoding.ByteString.Lazy instance Data.Snowchecked.Encoding.Class.IsFlake Data.ByteString.Lazy.Internal.ByteString -- | This module provides a conversion function between a Flake -- and a strict ByteString. The ByteString is the series of -- bytes that make up the Flake, with the lower bytes being in -- the lower indecies. module Data.Snowchecked.Encoding.ByteString instance Data.Snowchecked.Encoding.Class.IsFlake Data.ByteString.Internal.ByteString -- | This generates unique (guaranteed) identifiers build from a timestamp, -- counter, and node id. Identifiers are convertible to values which are -- monotonically increasing with respect to time. module Data.Snowchecked -- | Create a new generator. Takes a configuration and node id. The node id -- may be any value that fits in a Word256, but it will be -- truncated to the number of bits specified in the provided -- configuration. newSnowcheckedGen :: MonadIO io => SnowcheckedConfig -> Word256 -> io SnowcheckedGen -- | Generates the next id. nextFlake :: MonadIO io => SnowcheckedGen -> io Flake -- | Configuration that specifies how many bits are used for each part of -- the id. These values are not validated and may be any legal value for -- the type. -- -- The default value provided by def is 64 bits in total length, -- just like the original Snowflake algorithm. -- -- Note that specifying 0 check bits results in the normal Snowflake -- generation. Setting confTimeBits or confCountBits near -- zero will significantly limit the total number of UIDs that can be -- generated, as well as the throughput of the UID generation. data SnowcheckedConfig SnowcheckedConfig :: Word8 -> Word8 -> Word8 -> Word8 -> SnowcheckedConfig -- | Number of bits used to hold the time [confTimeBits] :: SnowcheckedConfig -> Word8 -- | Number of bits used to count instances per-time [confCountBits] :: SnowcheckedConfig -> Word8 -- | Number of bits derived from the node id [confNodeBits] :: SnowcheckedConfig -> Word8 -- | Number of bits used to store the checksum [confCheckBits] :: SnowcheckedConfig -> Word8 -- | The state that needs to be communicated between flake generation -- calls. This should be treated as opaque by consumers of this library: -- messing about with its internals may cause your code to hang -- indefinitely. data SnowcheckedGen -- | The state of a given generated instance. Note that the actual value is -- calculated on demand. data Flake -- | Calculates the number of bits in each Flake generated using a -- given configuration. It returns a Word32 because there are 4 -- fields and the bitlength of each field fits in a Word8, so the -- total bit count must fit within a Word32. snowcheckedConfigBitCount :: SnowcheckedConfig -> Word32 -- | Provides the count of total number of unique flakes possibly generated -- by a node using this configuration. uniqueFlakeCount :: SnowcheckedConfig -> Integer -- | This module provides a generalized conversion function between a -- Flake and all types that are members of both FromText -- and ToText. It is specialized for the strict Text and -- String types. It is marked as incoherent due to the constraint -- being no smaller than the instance type, so it is undecidable. -- -- To specify how you want the conversion to be performed, you need to -- wrap the text-like type the Base16 constructor. Other encodings -- (eg: Base64) may be added later. -- -- Note that when converting to a Flake, the implementation -- silently discards characters other than digits, a-f, -- and A-F. This allows you to apply formatting to the -- Flake. module Data.Snowchecked.Encoding.Text instance (Data.Text.Conversions.ToText a, Data.Text.Conversions.FromText a) => Data.Snowchecked.Encoding.Class.IsFlake (Data.Text.Conversions.Base16 a)