CSE 532 Spring 2008: Lab 3

Lab 3: "Interceptors and Service Reconfiguration"

Points: 25% of final grade

Submitted: by electronic submission to cse532@cec.wustl.edu

Due: by 11:59pm Sunday May 4, 2008

Purpose

In this assignment you will again use the basic wrapper facades for networked OO programming provided by the ACE framework, that you used in the previous labs. In this lab you will refactor and extend your lab 2 solution to provide the ability to reconfigure features of your client and server programs dynamically at run-time through a simple textual user interface. This will require you to think carefully about how your client and server programs require and provide different kinds of services, and how changes to those services can be made responsively, but in a carefully controlled manner.

In addition to providing a thorough writeup of your solution for this lab, and of how your lab designs and implementations have evolved throughout the semester, this assignment will require you to implement the following new capabilities in both your client and server programs:

1. make your client and server programs repetitive, so that once a game has completed a new game of that same kind with that same name is started, and the clients and servers continue to run in that way until they are either terminated or reconfigured to play different games (after which the games in progress will either end naturally or be safely and consistently cancelled, at your discretion);

2. add support for a third kind of poker game, called "hold 'em", in which each player receives 2 cards of their own (called "hole cards"), and all players share 5 common cards (called "table cards");

3. control interfaces so that client and server services can be reconfigured dynamically, and so that changes can be made to those services safely while the client and server programs are running;

4. a responsive textual user interface that accepts reconfiguration commands and dispatches them to the appropriate parts of your client and server programs, while the clients and servers are running;

5. interceptors at appropriate points in your client and server programs so that reconfiguration events can be sent and detected in order to trigger consistent changes to those programs along end-to-end communication paths; and

6. control mechanisms that when invoked by the interceptors enact the appropriate changes to the services, and which use the services' control interfaces to ensure changes are made safely while the clients and servers are running.

Optionally, you will also have the opportunity to add features for extra credit as described below, which include:

1. the ability to support remote reconfiguration through flooding of admin commands (as noted above) so that reconfiguration can be done locally or remotely; or

2. adding timers to the lowest level event handling layers on the server and the clients in order to vary their duty cycles according to a (re)configuration command that should specify the on-interval and off-interval of each duty cycle.

Assignment

You will extend your lab 2 implementation to define a textual configuration command language that expresses the different configuration options for your client and server programs. You will also implement a simple textual user interface (UI) that can read those configuration commands from each client or server's standard input (for example using the cin standard input iostream), recognize the commands and their parameters, and invoke the appropriate mechanisms to ensure the commands are carried out. You will need to think about which thread(s) will manage this interface, which could be done either reactively or (probably easier) via a separate dedicated UI thread.

You will need to think about the different design dimensions of your client and server programs, along the lines discussed in Chapter 2 of the C++NPv2 textbook. This will help you decompose your design into distinct "services" that can be reconfigured more or less independently. For example, one idea may be to consider each game to be a separate service, since each instance of a game type many be configured independently of the others. Alternatively it may make more sense to have the entire clients and servers be the reconfigurable services since that is the level at which many of the reconfiguration commands are targeted. Depending on how you have designed your client and server programs, there may be other abstractions that can be configured independently, and perhaps might even replace the game instances as configurable services. Careful attention to this point may lead to some initial refactoring of your lab 2 design to make reconfiguration easier, which in the long run is likely to save more time than it costs.

For the remote command portion of the extra credit, each host (client or server) and each service you identify should be given a label, so that configuration commands can be directed to it. How you structure these labels is up to you, but one reasonable format for the labels based on the assumption that the games are configurable services would be host[:game] where "host" is the name given to the client or server on the command line, and "game" is the name given to the game on the command line.

Each of these distinct services should be given a configuration control interface similar to the one discussed in the Component Configurator lecture. You can apply these configuration control interfaces to individual objects, or (possibly by using the Facade or Extension Interface design patterns) to collections of related objects, as appropriate to isolate services from the effects of changes to other services, and to ensure changes to services are carried out consistently and safely.

You will design (or obtain from ACE or another framework) mechanisms to enact changes to services safely using those service control interfaces. In particular, some thought may be required into protocols for handshaking between configuration control mechanisms in different parts of a program or between programs, to ensure the changes are orchestrated safely, without risking deadlocks, race conditions, or other synchronization and concurrency hazards.

Finally, you will design and deploy interceptors at key points in your programs so that commands from the user and/or from other configuration mechanisms and/or interceptors are detected and dispatched appropriately (e.g., to local configuration mechanisms or to other interceptors).

To do this please perform the following tasks:

Application Features

You should also add support for a third kind of poker game, called "hold 'em", in which each player receives 2 cards of their own (called "hole cards"), and all players share the same 5 common cards (called "table cards"), and then form hands consisting of their hole cards and whichever 3 table cards make the highest ranking hand. As in the draw and stud poker games, the player should be dealt their hole cards by the server sending them to the players and removing them from the deck. For the table cards the server should move them from the deck into a separate data structure, and then communicate what they are to each of the players in the game.

One other difference is that for each player the hand for scoring should be first chosen by picking the highest ranking combination of 3 cards from the 5 table cards with that player's hole cards. Otherwise (e.g., the content of the deck that is used, how the 5 cards chosen for each player are scored, etc.) is similar to the stud and draw poker games you have implemented in your previous labs.

Configuration Commands and Input Interpreter

1. reads a line of text from the standard input stream,
2. parses the line of text until it recognizes a valid configuration command,
3. executes the command locally if appropriate, and
4. (extra credit only) passes the command along to any other client or server to which the command pertains.

This interpreter should run concurrently with the other activities of the client or server in which it is located. One straightforward way to achieve this is to make the interpreter an active object, with its own thread, and then add any synchronization mechanisms that are needed to avoid race conditions or other hazards when the interpreter thread interacts with other threads. Also, C++ iostreams and (especially) stringstreams can be very useful for parsing textual input (for a simple example of their use, please see the last few CSE 332 lecture slides on data and I/O).

The command language you design should include the following capabilities, though you are free to modify the syntax and/or semantics of these commands as long as (1) you document the differences thoroughly, and give examples of how each variation is to be used, in your lab writeup; and (2) all of the capabilities given here are still possible in the modified version. Note that much of the following discussion assumes that entire clients and servers are identified as distinct services, but if you choose a different service decomposition then you should update the definitions of these commands appropriately as needed.

The first set of commands is used to invoke and to configure features of the system's reconfiguration capabilities, and how the clients and servers interact with respect to them:

• define <filename> - opens a definition file for a client or server, which causes the server or client to discard all previous definitions (e.g., if your clients were started with a definition file as in lab 2, a define command that names a different file would replace the current definitions with a new one. If games based on the old definition are in play you should decide whether to terminate them or have them complete prior to discarding the old definitions, as long as the new definitions can take place immediately.

  For the servers, you should introduce a new kind of definition file that indicates what types of games the server knows how to play (code for all 3 should be available in all servers, it's just that well use this feature to give the servers "selective amnesia" about what their abilities are.

• process <filename> - opens the named file and parses each line of the file as a separate configuration command which the parser issues to the configuration framework. Note that files should be able to expand by containing instances of this same command that results in another file being opened - watch out for unbounded recursion, however: one reasonable solution that allows repetitive inclusion of a file but prevents unbounded recursion would be to (1) close each file after it has been fully parsed, (2) remember which files are currently open, and (3) disallow them being re-opened until they have been closed.

• current [label:<label>] [key:<value>] - prints out the current configuration of the host or service identified by the label. If no label is given, a reasonable default would be to print out the configurations of all of the services on the host on which the command was issued.

• (extra credit only)admin <local | key:<value> | global> [label:<label>] [key:<value>] - changes the administration mode of the service (or if no service is specified all services on the host) specified in the label parameter (if no label is given, a reasonable default would be to apply the command to all services on the host on which the command was issued).

  • If the administration mode for a service is set to local, then only commands issued directly on the host where the service resides should be processed (for any non-local commands, a suitable error message should be printed but the host should accept subsequent local commands while in that mode).

  • If the administration mode is set to key, then the service should remember the key value that was supplied in the second parameter to the admin command, and should only process configuration commands that either are issued locally or are accompanied by a matching key value (for any other commands, a suitable error message should be printed but the host should accept subsequent local or appropriately keyed commands while in that mode).

  • If the administration mode is set to global, then any command issued to the host should be processed.

  Notice that the last parameter to the admin command is an optional key parameter that can be used to authorize a remote command to change the administration mode, if the host was already in a keyed administration mode. A similar optional key paramter can be given for all other commands where the service's administration mode matters.

The second set of commands is used to configure the games played and how the clients and servers interact with respect to them:

• play <stud | draw | holdem> - tells a client or server that it knows how to play a kind of poker, after which a client will respond to definition file lines for that kind of game, or a server will respond to requests from players to play that kind of game, from that point until subsequent termination or a reconfiguration that turns off that ability.

• dontplay <stud | draw | holdem> - tells a client or server that it does not know how to play a kind of poker, after which a client will ignore definition file lines for that kind of game, or a server will refuse requests from clients to play that kind of game, from that point until subsequent termination or a reconfiguration that turns off that ability.

• suspend [<game name>] - pauses a client or server's handling of a game (or if no game name is given, all games) temporarily until a subsequent resume command for that game (or all games) is issued.

• resume [<game name>] - resumes a client or server's handling of a game (or if no game name is given, all suspended games).

EXTRA CREDIT: A bonus of up to 5 points (scores above 100 are possible) will be given to any team that does one or both of the following additions to their project:

1. gives the ability to support remote reconfiguration through flooding of labeled admin and configuration commands (as noted above) so that reconfiguration can be done locally or remotely; or

2. adds timers to the lowest level event handling layers on the server and the clients in order to vary their duty cycles according to an additional (re)configuration command that should specify the on-interval and off-interval of each duty cycle.

Teams are encouraged to try either or both of these options, and to document the designs and experiences with them in the lab writeup. Full or partial credit of as much as 5 points total will be awarded for any non-trivial efforts on these.

Service Interfaces

• init - tells a service to (re)initialize itself based on a definition file.

• fini - tells a service to terminate itself.

• suspend - tells a service to suspend itself.

• resume - tells a service to resume itself.

• info - querys a service about its current configuration status plus any other relevant attributes (such as its label, its administration mode, its key value if any, etc.).

However, depending on how you have implemented your client and server programs, it is also possible that for one or more interceptors a different interaction sequence may be more appropriate between that interceptor and one or more of the services it configures (for example, to ensure safety or to keep the implementations of the service interface methods above from becoming overly complex). In that case you are free to vary how any interceptor interacts with the service(s) it configures, as long as you justify that decision in your lab writeup.

Interceptors and Service Repository

One approach is to intercept configuration commands in-band, and apply special handling as needed to prevent commands from being interpreted as being application data (for example if commands are forwarded along the normal data transmission paths between clients and servers). This approach has the advantages that (1) the existing lab 2 infrastructure can be re-used significantly, and (2) commands often can be intercepted and dispatched efficiently within the handlers they affect, but the disadvantage that (3) special processing (and possibly revisions to the data transmission format) must be added to distinguish commands from non-command data.

Another approach is to intercept configuration commands entirely out-of-band in which case special purpose communication paths (e.g., built using new handlers, sockets, etc.) should be added in order to separate the command-related traffic from the data traffic. This approach has the advantage of (1) distinguishing the two kinds of traffic explicitly, but has the disadvantage that (2) new acceptors, connectors, and service handlers need to be provisioned for the command handling paths, along with the necessary concurrency and synchronization mechanisms to integrate them safely with the existing data management infrastructure from lab 2.

A third approach is to combine the out-of-band approach with the in-band approach and selectively distinguish data traffic from command traffic only at key points in the architecture where the disadvantages of doing so are less, and/or the advantages of doing so are greater. In either case, please think carefully about the trade-offs in safety, performance, and complexity, and please write up your decisions as part of your expanded README file, per the discussion of the writeup portion of the assignment below.

Testing

First make sure that the basic features function correctly, and then define and execute more sophisticated scenarios to test the different sequences of potentially interacting configuration commands that cannot be tested thoroughly simply by exercising each command individually.

Writeup

Resources

Wrapper Facades

• ACE_Service_Object -- declares interfaces for initialization, termination, suspension, and resumption of reactor event handlers
• ACE_Service_Repository -- stores and provides access to service objects
• ACE_Acceptor -- a generic abstraction for accepting socket connection requests
• ACE_Connector -- a generic abstraction for requesting network connections
• ACE_Get_Opt -- an option-string parameterized abstraction for parsing command line arguments
• ACE_INET_Addr -- an internet domain socket abstraction
• ACE_Reactor -- a generic abstraction for reactive event demultiplexing
• ACE_SOCK_Acceptor -- an acceptor abstraction for sockets
• ACE_SOCK_Connector -- a connector abstraction for sockets
• ACE_SOCK_Stream -- an internet domain stream socket abstraction
• ACE_Svc_Handler -- a full featured service handler abstraction
• ACE_Thread_Manager -- a class used for managing threads directly
• ACE_Thread_Manager -- a class used for managing threads directly
• ACE_TSS -- an implementation of thread specific storage
• ACE_Guard -- an implementation of a guard for scoped locking
• ACE_Thread_Manager -- a class used for managing threads directly
• ACE_Null_Mutex -- implements a do-nothing mutex (for strategized locking)
• ACE_Thread_Mutex -- implements a thread mutex synchronization object
• ACE_Recursive_Thread_Mutex -- wraps or emulates a recursive thread mutex
• ACE_RW_Thread_Mutex -- implements a readers/writer thread mutex
• ACE_Null_Semaphore -- implements a do-nothing semaphore (for strategized locking)
• ACE_Thread_Semaphore -- implements a thread semaphore synchronization object
• ACE_Condition_Thread_Mutex -- implements a thread mutex condition variable
• ACE_Message_Queue -- implements a queuing layer used with multi-threading
• ACE_Task -- active object that can interoperate with other threads, reactors, etc.

Service dimensions and the Service Configurator framework in ACE are discussed in detail in chapters 2 and 5 of the C++NPv2 book:

• Schmidt and Huston C++ Network Programming, Volume 2, Addison-Wesley, 2003.

The Reactor and Acceptor/Connector pattern implementations in ACE are discussed in detail in chapters 3, 4, and 7 of the C++NPv2 book.

The concurrency and synchronization pattern implementations and wrapper facades in ACE are discussed in detail in chapters 5, 6, 9, and 10 of the C++NPv1 book:

• Schmidt and Huston C++ Network Programming, Volume 1, Addison-Wesley, 2003.

Implementation of the Active Object and Half-Sync/Half-Async patterns and their associated wrapper facades is discussed in detail in chapter 6 of the C++NPv2 book.

STL Iterators and Algorithms

• input iterators -- Austern 7.2, pp. 94-96
• output iterators -- Austern 7.3, pp. 96-100
• istream_iterator -- Austern 14.2.1, pp., 354-357
• ostream_iterator -- Austern 14.2.2, pp., 357-359
• for_each algorithm - Austern 11.4, pp. 218-220
• copy algorithm - Austern 12.1.1, pp. 233-235
• transform algorithm -- Austern 12.3, pp. 240-243
• unary function objects -- Austern 8.1.2, pp. 111-112
• sequence containers -- Austern 5.3.1, pp. 73-75
• list container class -- Austern 16.1.2, pp. 441-448

Makefile & Environment

You will need a Makefile that links appropriately with the ACE libraries and include files. Please feel free to adapt or use the Makefile from your lab 2 solution.

What to Submit

README

The first section of your README file should include:

1. the number of the lab (e.g., "CSE 532 Spring 2008 Lab 3")
2. the names and e-mail addresses of all team members
3. an overview of how your programs are designed,
4. the Wrapper Facades you used or extended and how they helped in your design and code,
5. any insights and questions you encountered while completing the assignment, and
6. if you are applying for extra credit please also describe the additional configuration capabilities your approach supports, explain your design and implementation choices for them, and give instructions for how to use and test them.

The second section of your README file should provide a detailed discussion of how your lab solutions evolved during the semester, from lab 0 through lab 3. For each of the lab assignments, please discuss

1. what the main design challenges were,
2. which of the design patterns we discussed in the course were applied in your lab solution,
3. how those design patterns helped address the design challenges you faced,
4. why you chose those design patterns instead of other alternatives (if any), and
5. how your implementation reflected the design patterns you chose (for example, which classes in your implementation played which roles in which patterns).

The third section of your README file should provide detailed instructions for how to:

1. unpack your files,
2. build your programs, and
3. run your programs.

Electronic Submission

1. your source code files,
2. your Makefile,
3. any example files you think useful, and
4. your README file.

Please send a separate copy of your README file, with clear instructions on how your submission file was produced and how to unpack it using tools available on the CEC Linux machines.

Grading

Correct Compilation and Operation

Design Quality

Implementation Quality

Coding Style

Documentation

Missing Files

Late Submission

Grading Issues from Previous Labs

• using hard coded constants
• using dynamic allocation when a class member would do: if it's dynamically allocated in the constructor and dynamically deallocated in the destructor, then there must be some reasonable design force that motivates this approach rather than using an object directly as a member of the class (which your readme file should of course please explain)
• using the same error message for different failures
• using a pointer/size arithmetic formula without a comment explaining it: in general any non-obvious code should have a comment giving an intuition of what it does in general terms (and even better explaining why or how it does it that way)
• putting non-inline function definitions in a header file
• initializing class members in the constructor body when it is possible to intialize them in the base/member initialization list
• initializing class members in the base member initialization list when that initialization could fail, e.g., when a function whose return value matters or that could throw an exception is called
• unnecessary format restrictions, e.g., not tolerating blank lines and extra whitespace in a file
• leaving "commented out" code fragments left in code - remove these or use conditional compilation to bring them in/out
• adding comments for things that are already fairly obvious from the code (e.g., begin and end of a method)
• using exit to end the program in the middle of a class method or any method that could be called from another method
• using fixed length buffers when the lengths of inputs to them are variable/unknown
• unnecessarily cramping symbols or lines together, which impacts readability - use whitespace generously: it's free!

• use precompilation include guards in header files to avoid duplicate inclusion:
  
#if ! defined (MY_FILE_H)
#define MY_FILE_H

// body of the header file

#endif /* defined MY_FILE_H */


• check the return value from any call that could return an error code after a failure (e.g., new (nothrow) )
• use try/catch blocks around any call that could throw an exception after a failure (e.g., new)
• use the constructor's base/member initializer list in preference to the body of the constructor for member intialization, except were it is necessary to use the constructor body (please see above)
• using typed constant variables with descriptive names in preference to precompiler #define macros
• use consistent and appropriate comments
• use inlining for efficiency, and use the technique in ACE that allows inlining to be turned on or off by a precompilation macro
• discuss design decisions in your README file
• ask remaining questions you have in your readme (!)
• test your code for its handling of error cases as well as of the "happy path"
• perform "tiger team" testing - take turns trying to find cases that break your program, and then fixing them
• using the string class for variable length character buffers
• using whitespace generously: it's free and it improves readability!