Client library for the MTGNet RPC protocol.
1AboutCL-MTGNET is a client library for the MTGNet RPC protocol. The libraryhandles all the details of marshalling and unmarshalling, includingmatching out-of-order responses to the appropriate request.
2DependenciesThis library depends on the CL-NETSTRING+ library, as well as thequicklisp-installable CL-JSON and TRIVIAL-UTF-8 libs.
3APIRemote methods are treated like FFI calls: the client createsdefinitions for the methods it wishes to use, and can then callthose methods as if they were local functions.
3.1Method DefinitionMost clients will want to use the high-level macros to definemethod functions that handle the details of calling. The methoddefinition macro is relatively simple:
(defmacro define-rpc-method ((method &optional service &key notification) &body args))
service are symbols naming the method and the
method belongs to.
define-rpc-method will create a
<method>, which takes a socket stream, a symbol
naming the service, and the arguments of the method. If
is provided, the function will be named
will not take a service symbol as a parameter. Note that both
service symbols will be processed by CL-JSON, so
the standard name-mangling applies (e.g.
describeMethod when sent to the server).
notification is not supplied or is
nil, the function will
return a future object that will return the value of the method (or
signal an error) when
wait is called on it. If
nil, the function will return immediately with no value
(since no response is expected from the server).
;; Define a method without specifying a service (define-rpc-method ;; Method name (describe-method) ;; Method arguments method-name) ;; Invoke the method on the 'server' service ;; (wait (describe-method sock 'server "version")) => [...] ;; Define a method on a specific service (define-rpc-method (describe-method server) method-name) ;; (wait (server-describe-method "version")) => [...] ;; Define a notification method (define-rpc-method (poke server :notification t) msg) ;; Note the lack of a WAIT call here ;; (server-poke "Poked for no reason!") => No value
3.2Batched CallsThe MTGNet protocol features the ability to send requests to theserver in a batch, with the guarantee that the server will hold theresponses for those calls until they're all ready before returningthem. Clients can submit a batch of calls using the
;; With STREAM, DESCRIBE-METHOD and VERSION defined elsewhere... (let (describe-future version-future) (with-batch-calls (setf describe-future (server-describe-method sock "version") version-future (server-version sock))) (values (wait description-future) ;; This will return immediately (wait version-future)))
Any method calls made within a
with-batch-calls macro won't be
submitted to the server until the end of the block. Note: since
none of the calls in a
with-batch-calls block will be submitted
until the block is left, calling
wait on one of the returned
futures will deadlock.
3.3FuturesThe non-notification functions created with
define-rpc-methodreturn a future object that will hold the return value of themethod or signal an error if there was one.
waitcan be used toretrieve a completion value or signal an error: it takes a futureobject, and returns when that future completes.
Right now the underlying IO mechanism isn't really
wait drives the IO processing, so if a lot of
requests are made and
wait is never called, the socket buffer
could fill and cause the server to block. This shouldn't be an
issue under most workloads, however.
- Use an asynch IO mechanism to avoid the need to call
- Add timeouts and keepalive options for rpc methods.
- Accept strings as well as symbols for method and service names.
- Use typespec values from the server to do typechecking wherepossible.
- This could be a performance issue, so this may need to be adisable-able feature.
- Allow clients to specify non-mangled names?
- Document signaled conditions once they're all in place.
- Give the client some control over the encoding of arguments passedto methods.
- Either allow client to supply pre-encoded values (potentialbadness here), or supply encoder functions.