diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,1 +1,3 @@ # zeromq4-simple + +Some extra type-level constraints over [zeromq4-haskell](https://hackage.haskell.org/package/zeromq4-haskell)'s design. diff --git a/src/System/ZMQ4/Simple.hs b/src/System/ZMQ4/Simple.hs --- a/src/System/ZMQ4/Simple.hs +++ b/src/System/ZMQ4/Simple.hs @@ -12,6 +12,19 @@ , UndecidableInstances #-} +{- | +Module: System.ZMQ4.Simple +Copyright: (c) 2018, 2019 Athan Clark +License: BSD-3 +Maintainer: athan.clark@gmail.com +Portability: GHC + +Some simple type-level constraints over the 'System.ZMQ4.Monadic' module - it uses +type families and phantom types to enforce semantically correct connections with +respect to ZeroMQ's design. +-} + + module System.ZMQ4.Simple where import System.ZMQ4.Monadic @@ -40,9 +53,10 @@ -- * Types +-- | A measure of how many peers a connection can have. data Ordinal = Ord1 | OrdN --- | The numerity of `from` +-- | How many `to`'s' a `from` can have. type family Ordinance from to (loc :: Location) :: Ordinal where Ordinance Pair Pair 'Bound = 'Ord1 Ordinance Pair Pair 'Connected = 'Ord1 @@ -67,15 +81,16 @@ Ordinance Push Pull 'Connected = 'OrdN Ordinance Push Pull 'Bound = 'Ord1 - +-- | Connections that need a 'ZMQIdent'. type family NeedsIdentity from to :: Constraint where NeedsIdentity Req Router = () NeedsIdentity Dealer Rep = () NeedsIdentity Dealer Router = () - +-- | Whether a socket is a client or a server. data Location = Connected | Bound +-- | The type of sockets that can be bound to a host. type family Bindable from :: Constraint where Bindable Pair = () Bindable Rep = () @@ -87,6 +102,7 @@ Bindable Pull = () Bindable Push = () +-- | The kind of sockets that can be connected to a (remote) host. type family Connectable from :: Constraint where Connectable Pair = () Connectable Req = () @@ -100,18 +116,18 @@ Connectable Pull = () Connectable Push = () - +-- | Simple wrapper with extra phantom types. newtype Socket z from to (loc :: Location) = Socket {getSocket :: Z.Socket z from} - +-- | Legal socket connection combinations type family IsLegal from to :: Constraint where IsLegal Pair Pair = () IsLegal Sub Pub = () IsLegal Pub Sub = () - IsLegal XSub Pub = TypeError (Text "Not legal ZeroMQ socket: For some reason xsub/pub isn't working") + IsLegal XSub Pub = TypeError ('Text "Not legal ZeroMQ socket: For some reason xsub/pub isn't working") IsLegal XPub Sub = () - IsLegal Pub XSub = TypeError (Text "Not legal ZeroMQ socket: For some reason pub/xsub isn't working") + IsLegal Pub XSub = TypeError ('Text "Not legal ZeroMQ socket: For some reason pub/xsub isn't working") IsLegal Sub XPub = () IsLegal XPub XSub = () IsLegal XSub XPub = () @@ -127,29 +143,32 @@ IsLegal Dealer Router = () IsLegal Router Router = () IsLegal Dealer Dealer = () - IsLegal from to = TypeError (Text "Not legal ZeroMQ socket") - + IsLegal from to = TypeError ('Text "Not legal ZeroMQ socket") +-- | Build a socket. socket :: SocketType from => IsLegal from to => from -> to -> ZMQ z (Socket z from to loc) socket from _ = Socket <$> Z.socket from +-- | Bind that socket to a host. bind :: Bindable from => Socket z from to 'Bound -> String -> ZMQ z () bind (Socket s) x = Z.bind s x +-- | Connect that socket to a (remote) host. connect :: Connectable from => Socket z from to 'Connected -> String -> ZMQ z () connect (Socket s) x = Z.connect s x - +-- | Represents some kind of identifier for a ZeroMQ socket. newtype ZMQIdent = ZMQIdent {getZMQIdent :: ByteString} deriving (Show, Eq, Ord, Generic, Hashable) +-- | Generate a 'ZMQIdent' via UUID. newUUIDIdentity :: IO ZMQIdent newUUIDIdentity = (ZMQIdent . LBS.toStrict . UUID.toByteString) <$> nextRandom - +-- | Tell ZeroMQ that you want your socket to be identified by this 'ZMQIdent'. setIdentity :: NeedsIdentity from to => Socket z from to loc -> ZMQIdent -> ZMQ z Bool @@ -158,7 +177,7 @@ Nothing -> pure False Just ident -> True <$ Z.setIdentity ident s - +-- | Set a random 'ZMQIdent' via UUID. setUUIDIdentity :: NeedsIdentity from to => Socket z from to loc -> ZMQ z () setUUIDIdentity s = do ident <- liftIO newUUIDIdentity @@ -168,7 +187,7 @@ -- * Classes --- | Send a message over a ZMQ socket +-- | Send a message over a ZMQ socket - @aux@ is possibly necessary additional information to send. class Sendable from to aux | from to -> aux where send :: aux -> Socket z from to loc -> NonEmpty ByteString -> ZMQ z () @@ -210,7 +229,7 @@ send (ZMQIdent addr) (Socket s) (x:|xs) = Z.sendMulti s (addr :| "":x:xs) --- | Receive a message over a ZMQ socket +-- | Receive a message over a ZMQ socket - @aux@ is possibly necessary additional information sent. class Receivable from to aux | from to -> aux where receive :: Socket z from to loc -> ZMQ z (Maybe (aux, NonEmpty ByteString)) diff --git a/zeromq4-simple.cabal b/zeromq4-simple.cabal --- a/zeromq4-simple.cabal +++ b/zeromq4-simple.cabal @@ -1,29 +1,31 @@ --- This file has been generated from package.yaml by hpack version 0.21.2. +cabal-version: 1.12 + +-- This file has been generated from package.yaml by hpack version 0.31.2. -- -- see: https://github.com/sol/hpack -- --- hash: 2a99200b850346f7f72e5b0ab742314015655ab8d06c5ac016a0bfd2e031a2f9 +-- hash: 1c511c7f2be6e9a8547e2f2a01b602ac98b742e3835853a1f61af213b8c22268 name: zeromq4-simple -version: 0.0.0 +version: 0.0.0.1 synopsis: More constrained extensions to zeromq4-haskell -description: Please see the README on GitHub at +description: Please see the README on GitHub at category: System, FFI +homepage: https://github.com/athanclark/zeromq4-simple#readme +bug-reports: https://github.com/athanclark/zeromq4-simple/issues author: Athan Clark -maintainer: athan.clark@localcooking.com -copyright: 2018 (c) Local Cooking Inc. +maintainer: athan.clark@gmail.com +copyright: 2018, 2019 (c) Athan Clark license: BSD3 license-file: LICENSE build-type: Simple -cabal-version: >= 1.10 - extra-source-files: - ChangeLog.md README.md + ChangeLog.md source-repository head type: git - location: git://git.localcooking.com/tooling/zeromq4-simple + location: https://github.com/athanclark/zeromq4-simple library exposed-modules: