-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Cloud Haskell Extended Process Registry -- @package distributed-process-registry @version 0.1.0 -- | The module provides an extended process registry, offering slightly -- altered semantics to the built in register and -- unregister primitives and a richer set of features: -- -- -- -- -- -- It is possible to monitor a registry for changes and be informed -- whenever changes take place. All subscriptions are key based, -- which means that you can subscribe to name or property changes for any -- process, so that any property changes matching the key you've -- subscribed to will trigger a notification (i.e., regardless of the -- process to which the property belongs). -- -- The different types of event are defined by the KeyUpdateEvent -- type. -- -- Processes subscribe to registry events using monitorName or -- its counterpart monitorProperty. If the operation succeeds, -- this will evaluate to an opaque reference that can be used when -- subsequently handling incoming notifications, which will be delivered -- to the subscriber's mailbox as RegistryKeyMonitorNotification -- keyIdentity opaqueRef event, where event has the type -- KeyUpdateEvent. -- -- Subscribers can filter the types of event they receive by using the -- lower level monitor function (defined in this module - -- not the one defined in distributed-process' Primitives) and -- passing a list of filtering KeyUpdateEventMask. Without these -- filters in place, a monitor event will be fired for every -- pertinent change. module Control.Distributed.Process.Registry -- | Describes how a key will be used - for storing names or properties. data KeyType -- | the key will refer to a name (i.e., named process) KeyTypeAlias :: KeyType -- | the key will refer to a (per-process) property KeyTypeProperty :: KeyType -- | A registered key. Keys can be mapped to names or (process-local) -- properties in the registry. The keyIdentity holds the key's -- value (e.g., a string or similar simple data type, which must provide -- a Keyable instance), whilst the keyType and -- keyScope describe the key's intended use and ownership. data Key a Key :: !a -> !KeyType -> !(Maybe ProcessId) -> Key a keyIdentity :: Key a -> !a keyType :: Key a -> !KeyType keyScope :: Key a -> !(Maybe ProcessId) -- | The Keyable class describes types that can be used as registry -- keys. The constraints ensure that the key can be stored and compared -- appropriately. class (Show a, Eq a, Hashable a, Serializable a) => Keyable a -- | A phantom type, used to parameterise registry startup with the -- required key and value types. data Registry k v Registry :: ProcessId -> Registry k v registryPid :: Registry k v -> ProcessId start :: (Keyable k, Serializable v) => Process (Registry k v) run :: (Keyable k, Serializable v) => Registry k v -> Process () -- | Associate the calling process with the given (unique) key. addName :: Keyable k => Registry k v -> k -> Process RegisterKeyReply -- | Associate the given (non-unique) property with the current process. If -- the property already exists, it will be overwritten with the new -- value. addProperty :: (Keyable k, Serializable v) => Registry k v -> k -> v -> Process RegisterKeyReply -- | Register the item at the given address. registerName :: Keyable k => Registry k v -> k -> ProcessId -> Process RegisterKeyReply -- | Register an item at the given address and associate it with a value. -- If the property already exists, it will be overwritten with the new -- value. registerValue :: (Resolvable b, Keyable k, Serializable v) => Registry k v -> b -> k -> v -> Process RegisterKeyReply -- | Atomically transfer a (registered) name to another process. Has no -- effect if the name does is not registered to the calling process! giveAwayName :: Keyable k => Registry k v -> k -> ProcessId -> Process () -- | The (return) value of an attempted registration. data RegisterKeyReply -- | The given key was registered successfully RegisteredOk :: RegisterKeyReply -- | The key was already registered AlreadyRegistered :: RegisterKeyReply -- | Un-register a (unique) name for the calling process. unregisterName :: Keyable k => Registry k v -> k -> Process UnregisterKeyReply -- | The result of an un-registration attempt. data UnregisterKeyReply -- | The given key was successfully unregistered UnregisterOk :: UnregisterKeyReply -- | The given key was invalid and could not be unregistered UnregisterInvalidKey :: UnregisterKeyReply -- | The given key was not found (i.e., was not registered) UnregisterKeyNotFound :: UnregisterKeyReply -- | Lookup the process identified by the supplied key. Evaluates to -- Nothing if the key is not registered. lookupName :: Keyable k => Registry k v -> k -> Process (Maybe ProcessId) -- | Lookup the value of a named property for the calling process. -- Evaluates to Nothing if the property (key) is not registered. -- If the assignment to a value of type v does not correspond to -- the type of properties stored by the registry, the calling process -- will exit with the reason set to InvalidPropertyType. lookupProperty :: (Keyable k, Serializable v) => Registry k v -> k -> Process (Maybe v) -- | Obtain a list of all registered keys. registeredNames :: Keyable k => Registry k v -> ProcessId -> Process [k] -- | Monadic left fold over all registered names/keys. The fold takes place -- in the evaluating process. foldNames :: Keyable k => Registry k v -> b -> (b -> (k, ProcessId) -> Process b) -> Process b data SearchHandle k v -- | Tests whether or not the supplied key is registered, evaluated in the -- calling process. member :: (Keyable k, Serializable v) => k -> SearchHandle k v -> Bool -- | Evaluate a query on a SearchHandle, in the calling process. queryNames :: Keyable k => Registry k v -> (SearchHandle k ProcessId -> Process b) -> Process b findByProperty :: Keyable k => Registry k v -> k -> Process [ProcessId] findByPropertyValue :: (Keyable k, Serializable v, Eq v) => Registry k v -> k -> v -> Process [ProcessId] -- | Low level monitor operation. For the given key, set up a monitor -- filtered by any KeyUpdateEventMask entries that are supplied. monitor :: Keyable k => Registry k v -> Key k -> Maybe [KeyUpdateEventMask] -> Process RegKeyMonitorRef -- | Monitor changes to the supplied name. monitorName :: Keyable k => Registry k v -> k -> Process RegKeyMonitorRef -- | Monitor changes to the supplied (property) key. monitorProp :: Keyable k => Registry k v -> k -> ProcessId -> Process RegKeyMonitorRef -- | Remove a previously set monitor. unmonitor :: Keyable k => Registry k v -> RegKeyMonitorRef -> Process () -- | Await registration of a given key. This function will subsequently -- block the evaluating process until the key is registered and a -- registration event is dispatched to the caller's mailbox. await :: Keyable k => Registry k v -> k -> Process (AwaitResult k) -- | Await registration of a given key, but give up and return -- AwaitTimeout if registration does not take place within the -- specified time period (delay). awaitTimeout :: Keyable k => Registry k v -> Delay -> k -> Process (AwaitResult k) -- | The result of an await operation. data AwaitResult k -- | The name was registered RegisteredName :: !ProcessId -> !k -> AwaitResult k -- | The server was unreachable (or died) ServerUnreachable :: !DiedReason -> AwaitResult k -- | The operation timed out AwaitTimeout :: AwaitResult k -- | Used to describe a subset of monitoring events to listen for. data KeyUpdateEventMask -- | receive an event when a key is registered OnKeyRegistered :: KeyUpdateEventMask -- | receive an event when a key is unregistered OnKeyUnregistered :: KeyUpdateEventMask -- | receive an event when a key's owner changes OnKeyOwnershipChange :: KeyUpdateEventMask -- | receive an event when a key's lease expires OnKeyLeaseExpiry :: KeyUpdateEventMask -- | Provides information about a key monitoring event. data KeyUpdateEvent KeyRegistered :: !ProcessId -> KeyUpdateEvent owner :: KeyUpdateEvent -> !ProcessId KeyUnregistered :: KeyUpdateEvent KeyLeaseExpired :: KeyUpdateEvent KeyOwnerDied :: !DiedReason -> KeyUpdateEvent diedReason :: KeyUpdateEvent -> !DiedReason KeyOwnerChanged :: !ProcessId -> !ProcessId -> KeyUpdateEvent previousOwner :: KeyUpdateEvent -> !ProcessId newOwner :: KeyUpdateEvent -> !ProcessId -- | An opaque reference used for matching monitoring events. See -- RegistryKeyMonitorNotification for more details. data RegKeyMonitorRef -- | This message is delivered to processes which are monioring a registry -- key. The opaque monitor reference will match (i.e., be equal to) the -- reference returned from the monitor function, which the -- KeyUpdateEvent describes the change that took place. data RegistryKeyMonitorNotification k RegistryKeyMonitorNotification :: !k -> !RegKeyMonitorRef -> !KeyUpdateEvent -> !ProcessId -> RegistryKeyMonitorNotification k instance Typeable KeyType instance Typeable Key instance Typeable Registry instance Typeable LookupKeyReq instance Typeable LookupPropReq instance Typeable LookupPropReply instance Typeable InvalidPropertyType instance Typeable RegNamesReq instance Typeable UnregisterKeyReq instance Typeable UnregisterKeyReply instance Typeable KeyUpdateEventMask instance Typeable RegKeyMonitorRef instance Typeable KeyUpdateEvent instance Typeable RegistryKeyMonitorNotification instance Typeable RegisterKeyReq instance Typeable RegisterKeyReply instance Typeable GiveAwayName instance Typeable MonitorReq instance Typeable UnmonitorReq instance Typeable AwaitResult instance Typeable KMRef instance Typeable State instance Typeable QueryDirect instance Typeable SHashMap instance Typeable SearchHandle instance Keyable k => Show (GiveAwayName k) instance Keyable k => Eq (GiveAwayName k) instance Keyable k => Show (RegistryKeyMonitorNotification k) instance Keyable k => Eq (RegistryKeyMonitorNotification k) instance Generic KeyType instance Show KeyType instance Eq KeyType instance Generic (Key a) instance Show a => Show (Key a) instance Eq a => Eq (Key a) instance Generic (Registry k v) instance Show (Registry k v) instance Eq (Registry k v) instance Generic (LookupKeyReq k) instance Generic (LookupPropReq k) instance Generic LookupPropReply instance Generic InvalidPropertyType instance Show InvalidPropertyType instance Eq InvalidPropertyType instance Generic RegNamesReq instance Generic (UnregisterKeyReq k) instance Generic UnregisterKeyReply instance Eq UnregisterKeyReply instance Show UnregisterKeyReply instance Generic KeyUpdateEventMask instance Eq KeyUpdateEventMask instance Show KeyUpdateEventMask instance Generic RegKeyMonitorRef instance Eq RegKeyMonitorRef instance Show RegKeyMonitorRef instance Generic KeyUpdateEvent instance Eq KeyUpdateEvent instance Show KeyUpdateEvent instance Generic (RegistryKeyMonitorNotification k) instance Generic (RegisterKeyReq k) instance Generic RegisterKeyReply instance Eq RegisterKeyReply instance Show RegisterKeyReply instance Generic (GiveAwayName k) instance Generic (MonitorReq k) instance Generic UnmonitorReq instance Generic (AwaitResult k) instance Eq k => Eq (AwaitResult k) instance Show k => Show (AwaitResult k) instance Generic KMRef instance Show KMRef instance Generic (State k v) instance Generic QueryDirect instance Generic (SHashMap k v) instance Datatype D1KeyType instance Constructor C1_0KeyType instance Constructor C1_1KeyType instance Datatype D1Key instance Constructor C1_0Key instance Selector S1_0_0Key instance Selector S1_0_1Key instance Selector S1_0_2Key instance Datatype D1Registry instance Constructor C1_0Registry instance Selector S1_0_0Registry instance Datatype D1LookupKeyReq instance Constructor C1_0LookupKeyReq instance Datatype D1LookupPropReq instance Constructor C1_0LookupPropReq instance Datatype D1LookupPropReply instance Constructor C1_0LookupPropReply instance Constructor C1_1LookupPropReply instance Datatype D1InvalidPropertyType instance Constructor C1_0InvalidPropertyType instance Datatype D1RegNamesReq instance Constructor C1_0RegNamesReq instance Datatype D1UnregisterKeyReq instance Constructor C1_0UnregisterKeyReq instance Datatype D1UnregisterKeyReply instance Constructor C1_0UnregisterKeyReply instance Constructor C1_1UnregisterKeyReply instance Constructor C1_2UnregisterKeyReply instance Datatype D1KeyUpdateEventMask instance Constructor C1_0KeyUpdateEventMask instance Constructor C1_1KeyUpdateEventMask instance Constructor C1_2KeyUpdateEventMask instance Constructor C1_3KeyUpdateEventMask instance Datatype D1RegKeyMonitorRef instance Constructor C1_0RegKeyMonitorRef instance Selector S1_0_0RegKeyMonitorRef instance Datatype D1KeyUpdateEvent instance Constructor C1_0KeyUpdateEvent instance Constructor C1_1KeyUpdateEvent instance Constructor C1_2KeyUpdateEvent instance Constructor C1_3KeyUpdateEvent instance Constructor C1_4KeyUpdateEvent instance Selector S1_0_0KeyUpdateEvent instance Selector S1_3_0KeyUpdateEvent instance Selector S1_4_0KeyUpdateEvent instance Selector S1_4_1KeyUpdateEvent instance Datatype D1RegistryKeyMonitorNotification instance Constructor C1_0RegistryKeyMonitorNotification instance Datatype D1RegisterKeyReq instance Constructor C1_0RegisterKeyReq instance Datatype D1RegisterKeyReply instance Constructor C1_0RegisterKeyReply instance Constructor C1_1RegisterKeyReply instance Datatype D1GiveAwayName instance Constructor C1_0GiveAwayName instance Datatype D1MonitorReq instance Constructor C1_0MonitorReq instance Datatype D1UnmonitorReq instance Constructor C1_0UnmonitorReq instance Datatype D1AwaitResult instance Constructor C1_0AwaitResult instance Constructor C1_1AwaitResult instance Constructor C1_2AwaitResult instance Datatype D1KMRef instance Constructor C1_0KMRef instance Selector S1_0_0KMRef instance Selector S1_0_1KMRef instance Datatype D1State instance Constructor C1_0State instance Selector S1_0_0State instance Selector S1_0_1State instance Selector S1_0_2State instance Selector S1_0_3State instance Selector S1_0_4State instance Selector S1_0_5State instance Datatype D1QueryDirect instance Constructor C1_0QueryDirect instance Constructor C1_1QueryDirect instance Constructor C1_2QueryDirect instance Datatype D1SHashMap instance Constructor C1_0SHashMap instance Keyable k => Foldable (SearchHandle k) instance Keyable k => Functor (SearchHandle k) instance (Keyable k, Serializable v) => Binary (SHashMap k v) instance Binary QueryDirect instance Eq KMRef instance Hashable KMRef instance Keyable k => Binary (AwaitResult k) instance Binary UnmonitorReq instance Keyable k => Binary (MonitorReq k) instance Keyable k => Binary (GiveAwayName k) instance Binary RegisterKeyReply instance Serializable k => Binary (RegisterKeyReq k) instance Keyable k => Binary (RegistryKeyMonitorNotification k) instance Binary KeyUpdateEvent instance Resolvable RegKeyMonitorRef instance Hashable RegKeyMonitorRef instance Binary RegKeyMonitorRef instance Hashable KeyUpdateEventMask instance Binary KeyUpdateEventMask instance Binary UnregisterKeyReply instance Serializable k => Binary (UnregisterKeyReq k) instance Binary RegNamesReq instance Binary InvalidPropertyType instance Binary LookupPropReply instance Serializable k => Binary (LookupPropReq k) instance Serializable k => Binary (LookupKeyReq k) instance Linkable (Registry k v) instance Resolvable (Registry k v) instance (Keyable k, Serializable v) => Binary (Registry k v) instance (Show a, Eq a, Hashable a, Serializable a) => Keyable a instance Hashable a => Hashable (Key a) instance Serializable a => Binary (Key a) instance Hashable KeyType instance Binary KeyType