CSE 532 Fall 2015


Lab 3: "That ends this strange eventful history"

Points: 20% of final grade

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

Due: by 11:59pm Friday December 4, 2015 (please note the new deadline)


Purpose

The purpose of this assignment is to combine your experience with multi-threaded programming and synchronization techniques, with additional event handling and service acess and configuration techniques for networked concurrent distributed systems. In this lab you will also be allowed to leverage state-of-the-art C++ network programming libraries (specifically ACE) in developing your design and implementation for this assignment.

Visual Studio 2013 is not successfully compiling ACE on the Windows machines in Urbauer 218, so you should please use Visual Studio 2012 for this assignment.


Assignment

In this assignment you will work in groups of 1, 2, or 3 people (but not more) to

If you are working in a different team for this lab than in a previous lab, you are allowed to reuse code from any of your earlier lab solutions though if you do that you should please add comments acknowledging contributions from anyone who is not on your current team (and noting in which previous lab their contributions were made), to the code you submit.

Make separate copies of the (source and header) code files from lab 2 that you are using for this assignment, and put them into the directory where your new project for the Director program keeps its own source files, before adding them to that project. Not only can this (1) avoid confusing Visual Studio (with regard to which files to build, where to find the object files from them, etc.), but it also makes it easier to ensure (2) you have all the files when packaging up your solution to submit it, and makes it easier (3) to revert to a previously stable code base if a change you are trying doesn't pan out well.

In this assignment, you will again work with input files in similar formats as in the previous lab 2 assignment, but instead of working with a single script, multiple script files should be able to be specified and used.

For example, a program might be given two script files, partial_hamlet_act_ii_script.txt and partial_macbeth_act_i_script.txt for the first parts of Act II from William Shakespeare's "Hamlet, Prince of Denmark" and Act I from William Shakespeare's "Macbeth" respectively (text obtained from the Literature Page web site at http://www.literaturepage.com/read/shakespeare_hamlet.html), with corresponding configuration files hamlet_ii_1a_config.txt, hamlet_ii_1b_config.txt, and hamlet_ii_2a_config.txt for the first script file and macbeth_i_1_config.txt, macbeth_i_2a_config.txt, and macbeth_i_2b_config.txt for the second.

As in the previous labs, each scene fragment's configuration file gives the name of each character in the scene fragment along with their corresponding part file, e.g., Polonius_hamlet_ii_1a.txt and Reynaldo_hamlet_ii_1a.txt in hamlet_ii_1a_config.txt, Polonius_hamlet_ii_1b.txt and Ophelia_hamlet_ii_1b.txt in hamlet_ii_1b_config.txt, King_hamlet_ii_2a.txt and Queen_hamlet_ii_2a.txt and Rosencrantz_hamlet_ii_2a.txt and Guildenstern_hamlet_ii_2a.txt in hamlet_ii_2a_config.txt, FIRST_WITCH_macbeth_i_1.txt and SECOND_WITCH_macbeth_i_1.txt and THIRD_WITCH_macbeth_i_1.txt and ALL_macbeth_i_1.txt in macbeth_i_1_config.txt, MALCOLM_macbeth_i_2a.txt and DUNCAN_macbeth_i_2a.txt and SOLDIER_macbeth_i_2a.txt in macbeth_i_2a_config.txt, and LENNOX_macbeth_i_2b.txt and MALCOLM_macbeth_i_2b.txt and DUNCAN_macbeth_i_2b.txt and ROSS_macbeth_i_2b.txt in macbeth_i_2b_config.txt.

To complete this assignment please perform the following tasks:

Extensions to Support Multiple Plays

Producer program

Reactive Communication Scheme

Stopping Protocol

Termination Protocols

Please make sure to test your program with different combinations of plays running and available, and generating various start, stop, and termination events under those different conditions. Please make sure that your solution does not freeze up (deadlock) or suffer obvious (i.e., more than a second or two) delays in its operation or in the handling of events, that you don't see any output corruption or program crashes (which may indicate the presence of race conditions), and that the output generated is correct. Please also make sure that when a play is stopped the various objects involved with it are reset into a state where they can re-start that same play, perform another play, etc.


Extra Credit

For up to an extra 5 percent of the assignment's value (scores of up to 105 are possible) design and implement a protocol through which plays can tolerate missing or misordered lines in a character's part definition, assuming that whatever lines are given are correctly numbered in the order they would appear in the play from which they came (and are correctly numbered with respect to the order of lines in other character part definitions in the same scene fragment).

In particular, all lines that do appear should be delivered, they should be delivered in order with respect to each other and with respect to the other lines by other characters in the scene fragement, and the program should not experience deadlock or even undue delays due to missing or misordered lines.

One approach to this would be to have each Player sort their structured line data by number (thus also trivially solving the issue of lines being scrambled in the part definition file), and then inform the Director of all the contiguous ranges of their line numbers. The Director then could match up all the ranges from all the Players, identify any gaps in the line numbers, and then implement a protocol such that when a gap is reached the Director simply advances the current line counter to the start of the next range that some Player is ready to recite.

How you design this is up to you, though you should please test your solution thoroughly to ensure that whether or not lines are missing the program performs correctly in all other features as well as in the ones for extra credit. Please make sure to document your design decisions, and your rationale for them, as well as describing how you implemented this extra credit portion, in your project report under a section that is clearly identified as being for the extra credit portion.

You may request other options for extra credit, which I will approve if they are of similar complexity and of similar relevance to the assignment. Please send me e-mail with any such proposals and any that I accept will be posted here and in an e-mail that I'll send out to all students in the course.

The following additional extra credit options have been accepted and approved so far:


What to Submit

ReadMe.txt

As you work on your program, please write down the design decisions you faced, and describe both the solutions you chose to address them and the rationale for the choices you made, in the ReadMe.txt text file that should have been generated by Visual Studio 2012.

The first section of your ReadMe.txt file should include:

  1. the number of the lab (e.g., "CSE 532 Fall 2015 Lab 3")
  2. the names and e-mail addresses of all team members
  3. an overview of how your programs are designed, including all the design discussions requested above,
  4. the Wrapper Facades you used or extended and how they helped in your design and code, and
  5. insights, observations and questions you encountered while completing the assignment.

The second section of your ReadMe.txt file should provide detailed instructions for how to:

  1. unzip or otherwise unpack your files,
  2. build your program(s), and
  3. run your program(s) on the Urbauer 218 lab machines where we will evaluate your lab solutions.
Important:We must be able to receive your e-mail, and unpack, build, and run your programs using only the instructions in your ReadMe.txt file and the Visual Studio 2012 version and other tools available on the CEC Windows lab machines in Urbauer 218.

The third section of your ReadMe.txt file should provide a reasonably detailed description of how you evaluated your solution, including the kinds of configuration and character part files you used and their formats (including well formed and badly formed content, misordered lines, etc. to test how your program handled those variations), and any other scenarios that you tested that you consider important.

Please be thorough in writing up your project report, as it will be worth a full letter grade (10 percent) of the assignment overall.

Electronic Submission

Please submit by e-mail to cse532@seas.wustl.edu with a single .zip file attached containing:
  1. your source code and header files,
  2. any example files you think useful (for example, the different configuration and character part files you used to test your solution),
  3. output files from at least one significant test of your programs, and
  4. your ReadMe.txt file.

Please also send in a separate copy of your ReadMe.txt file, with clear instructions on how your submission file was produced and how to unpack it using tools available on the CEC lab machines. IMPORTANT:please make sure that no .exe file is included in any .zip file you send, as the WUSTL e-mail servers will block delivery of email with a .zip attachment that includes a .exe file. Please also make sure to send a .zip file (not a .7z file or other zip format) when you send your solutions.

Grading

Please treat this assignment as you would a commercial or research product that you are shipping to a large group of customers. Please take the time to test, document, and check your work to make sure all parts are shipped, are of high quality, and behave resonably under a range of different operating conditions. Grading will focus both on the quality of your solution and on the quality of the product itself, as it arrives at the cse532 account. To ensure the best possible result (and accordingly the highest possible grade), please pay attention to the following issues:

Correct Compilation and Operation

Your program must compile and run correctly on the CEC Windows lab machines using the source files you provide. Please make sure your program compiles without warnings (and of course without errors), and you might even want to try running it on different compilers (say also using g++ on shell.cec.wustl.edu or one of the other Linux servers) and fixing all the warnings for each. Missing files will be handled with a 5 point deduction (possibly per file) if you need to supply a new file in order for us to build your solution on the CEC Windows lab machines.

Design Quality

Design decisions are largely yours to make, and as long as the design is concise, coherent, consistent, and addresses all design forces in the assignment, you will receive full credit. One key area to consider is whether each abstraction in your design does a single job, does that job completely, and collaborates appropriately with other abstractions. Minor deductions (1-3 points, but please be aware minor deductions can add up) will be made for abstractions that are unnecessarily large or have inappropriate inter-dependencies. Major deductions (5-15 points) will be made for larger problems like neglecting key requirements of the assignment, code that does not compile or that crashes when it runs, etc.

Implementation Quality

How you implement your solution is again up to you, and we will take into account different approaches to implementation. Minor deductions will be made for things your program gets away with but are not good, like neglecting to check the return value from a system call or Wrapper Facade method (i.e., the program may have problems under special conditions), or calling exit(1) from inside a class method rather than providing a clean termination path. Major deductions will be made for problems that produce incorrect or extremely inefficient behavior of the program. The former kinds of errors should be eliminated during your coding and code review phases, and the latter kinds of errors should be eliminated during your testing phase, which should include running different combinations of configuration and character part files containing well formed and/or badly formed contents.

Coding Style

Different coding styles will also be accepted, as long as they are clear, readable, and consistent. Please code clearly with both the reader of the code and the user of the program in mind. Please use consistent indentation and placement of braces, and comment your code thoroughly. Use whitespace liberally - it's free and it makes it a lot easier to read your code. When grading, we will add tagged comments to the code indicating areas where we found particular issues to mention, whether or not points are deducted. Only minor deductions will be made for each style issue, except in extreme cases.

Documentation

Please make sure you provide adequate instructions on how to unpack, build, and run your program. Also, please make sure to document your solution. Minor or even major deductions will be made for inadequate explanation of how your solution does what it does, why you made key design choices, or how the user (or grader) can successfully build and run your program. Even if how you did something is obvious to you, please assume it is not obvious to the reader.

Missing Files

Missing files in the delivered software make it difficult or impossible to evaluate your solution. An automatic deduction of up to 5 points will be applied for each missing or corrupted file that is submitted later on request.

Late Submission

Labs recieved within 24 hours after the deadline will be graded with an automatic 10 point deduction. Labs received more than 24 hours after but within 48 hours of the deadline will be graded with an automatic 20 point deduction. Labs received after 48 hours from the deadline will not be graded, except under extenuating circumstances. If you are running late completing the assignment, please let us know about the trouble as soon as possible (and it may be possible to give you a brief extension if you request it sufficiently in advance of the deadline), and please turn in as much as you can before each deadline so we can give at least some credit for the work you have done.

Grading Issues from Previous Semesters

Please avoid the following practices, which have at least drawn at least comments (and possibly deductions depending on the extent of the issue) in previous semesters: Please use the following practices to improve the clarity and quality of your code and documentation:
Posted 6am Tuesday october 27, 2015, by Chris Gill.