Network.Mom.Stompl.Patterns.Desk

A Desk is a server that supplies information about providers. A client requests providers for a specific job (service, task or topic) and the desk will reply with a list of queue names of providers of the enquired job.

The desk is not statically configured, but uses a registry to which providers connect. Providers that cease to work can disconnect or, if heartbeats are required, will be removed from the list of available providers internally when no more heartbeats are sent. This way, the information provided by a desk is always up-to-date.

Desk balances providers, i.e. providers rotate in a list from which always the first n providers are handed out to requesting consumers (where n corresponds to the number of providers requested by the consumer.)

Since providers are managed dynamically, the result of two consecutive calls is probably not the same. Desk is thus not idempotent in the strict sense. But, since the call itself does only cause a change of the order of providers (and since it should be irrelevant for the consumer which provider is actually used), two consecutive calls will have the same effect -- if not all providers disconnect between the two calls.

Internally, the Desk protocol uses the following headers:

• jobs: Comma-separated list of providers;
• redundancy: Requested number of providers.

Documentation

withDesk :: Con -> String -> QName -> (Int, Int) -> OnError -> QName -> IO r -> IO r

Creates a desk with the lifetime of the application-defined action:

• Con: Connection to a Stomp broker;
• String: Name of the desk, used for error handling;
• QName: Registration queue -- this queue is used by providers to connect to the registry, it is not used for consumer requests;
• (Int, Int): Heartbeat range of the Registry (see withRegistry for details);
• OnError: Error handling;
• QName: Request queue -- this queue is used by consumers to request information about available providers;
• IO r: Action that defines the lifetime of the desk; the result is also the result of withDesk.

requestProvider :: ClientA () () -> Int -> JobName -> Int -> IO (StatusCode, [QName])

Function used by consumer to request provider information from a desk:

• ClientA () (): The request to the desk is sent through a client of type () (). This client must be created by the application beforehand (e.g.: the client could be created once during initialisation and then be used repeatedly to obtain or update information on providers according to the application needs);
• Int: Timeout in microseconds;
• JobName: Name of the job for which the consumer needs providers;
• Int: Number of providers needed by the consumer. This can be used for redundancy: if one provider fails, the consumer passes to the next. Be aware, however, that the information, at the point in time, when a provider fails, may already be outdated. Therefore, the redundant providers should be used immediately and, when the main provider fails later, the information should be updated by requesting new providers from the desk.

The result is a tuple of (StatusCode, [QName]). If the StatusCode is not OK, the list of QName will be empty; otherwise, it will contain at least one provider and maximum n providers (where n is the number of providers requested). If fewer providers than requested are available, the list will contain less than n providers. But note that this, as long as there is at least one provider, does not count as an error, i.e. the StatusCode is still OK.