From 907498bb9b06b0a3d9a9e71564b445929966ee85 Mon Sep 17 00:00:00 2001 From: Michael Bayne Date: Thu, 19 Jul 2001 05:55:35 +0000 Subject: [PATCH] Documented invocation services. git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@65 542714f4-19e9-0310-aa3c-eee0fc999fb1 --- docs/presents/design.txt | 100 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 96 insertions(+), 4 deletions(-) diff --git a/docs/presents/design.txt b/docs/presents/design.txt index d4d4ae62d..7d5443bc4 100644 --- a/docs/presents/design.txt +++ b/docs/presents/design.txt @@ -1,4 +1,4 @@ -Cher Mk3 Design -*- outline -*- +Cher Design -*- outline -*- * Why Cher? The basic function of this layer is to allow the sharing (Cher-ing) of @@ -6,8 +6,102 @@ information among different nodes in the network. Plus, I don't think Cher has ever had a software system named after her and it's high time. Imagine Cher as the social lubricant that allows the party goers to communicate. -* A note on thread-safety +* Overview +The Cher layer implements the distributed object services described in the +Cocktail design document. It does this within the context of an extensible +client/server application framework. Cher provides services that can be +integrated into your distributed application to share information between +a set of clients and entities operating on the server. +* Invocation services +To facilitate the client invoking code on the server (in a +request/response arrangement) and the server invoking code on the client +(in an asynchronous notification arrangement), the invocation services are +provided. + +We make use of reflection to make the invocation services feel a bit like +remote procedure calls. All invocation traffic is managed by the +invocation manager, part of which resides on the client and part on the +server. + +There are three classes involved when fully using the services. They are +the service class, the provider class and the receiver class. + +** Service class +The service class provides the client-side API to the request/response +component. For example: + +public class ChatService +{ + public void requestTell (String username, String message, + Object rsptarget); +} + +The tell() implementation would wrap the arguments up and pass them off to +the invocation manager for delivery to the server. If provided, the +response target object will receive a callback when the response comes in +from the server. The callback will come in the form of a call to a +reflected method on that object. The exact name of the method depends on +the implementation of the provider class which runs on the server. + +** Provider class +The provider class implements the server-end of the service and is +registered with the invocation manager on the server to handle a +particular class of invocations. Continuing with our example: + +public class ChatProvider +{ + public void handleTellRequest (int invid, String username, String message); +} + +The handleTellRequest() function will process the request and then +generate a response which is passed on to the invocation manager for +delivery to the client. The response will be named and the name of the +response will dictate the method that is invoked on the response target +object. The arguments that go along with the name must correspond to the +signature of that method. For example: + + invmgr.respond(invid, "TellFailed", new Object[] { "m.no_such_user" }); + +will result in: + + public void handleTellFailed (String reason); + +being called on the response target object. Because the response target +method is looked up only by name, all responses using the same name must +use the argument signature and the response target object may only have +one method with that particular name and its signature must match exactly +the signature dictated by the arguments. + +** Receiver class +For asynchronous messages from the server to the client, there exists the +receiver class. The receiver is registered with the client invocation +manager to handle messages of a particular type (much like the provider +class is registered on the server) which is identified by a string name. + +The receiver class provides methods named like so: + +public class ChatReceiver +{ + public void handleTellNotification (String from, String msg); +} + +where the arguments to the method again correlate with the arguments in +the invocation message. + +The server wrapper that generates the corresponding invocation message for +delivery to the client will likely also reside in the ChatProvider class +already described. For example: + +public class ChatProvider +{ + public void sendTell (BodyObject to, String from, String msg); +} + +This function will simply wrap up the arguments and pass them to the +invocation manager for delivery to the appropriate client. + +* A note on thread-safety Distributed objects are designed only to be accessed from one thread. On the server, there is a distributed object dispatch thread on which 95% of all activity takes place anyway. It would be questionable to require that @@ -35,7 +129,6 @@ need to fetch values from a distributed object after another thread has already started, you'll just have to rethink your approach. * Client components - ** DObjectManager Manages object proxies; converts value change requests into events, forwards them via the iomgr; dispatches events on incoming queue; reaps @@ -66,7 +159,6 @@ connection + authentication (logon) and disconnection (logoff); provides access to omgr and client dobj * Server components - ** Connection Manager Listens on accepting socket; creates and manages connection objects; informs connection observer of state changes; handles all network traffic