CSE 532 Fall 2021


Lab 3: "That ends this strange eventful history"

Points: 20% of final grade

Submitted: by electronic upload in Canvas

Due: by 11:59pm Friday December 10, 2021


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 additional C++ network programming libraries, specifically the ADAPTIVE Communication Environment (ACE), in developing your design and implementation 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 for the lab 3 Director program. This can make it easier (1) to ensure you have all the files when packaging up your solution to submit it, and (2) 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 or duplicated line numbers. In particular, all lines that do appear should be delivered in an appropriate partial order (how you order duplicate lines is up to you but you should please state what convention you adopted for that, in your write up for the extra credit part).

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 line numbers are missing, misordered, and/or duplicated 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.

Alternatively, (for up to an extra 5 percent of the assignment's value) instead of the centralized approach described above (which may be a bit more straightforward to design), develop a distributed approach to detecting and handling missing lines, e.g., based on timeouts, barrier synchronization, and possible a signaling protocol among the players in a play. This may require each player to record information about its progress, the progress of other players, and then may require each player to use timed waits in combination with recording that information, to avoid deadlock.

However you design your approach, please provide both a detailed explanation of your implementation, and a rationale for how it avoids deadlock and delivers all the lines that are available, in your project report.


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 your ReadMe.txt text file.

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

  1. the number of the lab (e.g., "CSE 532 Fall 2021 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 Linux Lab server machines where I will evaluate your lab solutions.
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.

Electronic Submission

Please upload, to the assignment page for this lab in Canvas, a single .zip (or .tar.gz) file containing:
  1. directories with your source code and header files and a Makefile for building your Director and Producer programs,
  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.


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 submitted. 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 Linux Lab machines using the source files you provide. Please make sure your program compiles without warnings (and of course without errors), using g++ (gcc-8.3.0) on the Linux Lab machines. 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 Linux 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 Tuesday November 9, 2021, by Chris Gill.