Init hw8

hw8/README.md

@@ -0,0 +1,27 @@
+# hw8
+
+## Tasks
+
+To fulfill **hw8** you have to solve:
+
+- task1
+- simu1
+- simu2
+
+## Files
+
+You find already or reuse some files for rust tasks. Please remember to use cargo to create a new project for each task and copy the given files into their dedicated directories.
+
+## Pull-Request
+
+Please merge any accepted reviews into your branch. If you are ready with the homework, all tests run, please create a pull request named **hw8**.
+
+## Credits of hw8
+
+| Task     | max. Credits | Comment                 |
+| -------- | ------------ | ----------------------- |
+| task1    | 3            | `ANSWERS.md` important! |
+| simu1    | 0,5          |                         |
+| simu2    | 0,5          |                         |
+| Deadline | +1           |                         |
+| =        | 5            |                         |

hw8/simu1/Makefile

@@ -0,0 +1,23 @@
+
+FLAGS = -Wall -pthread -g
+
+all: main-race main-deadlock main-deadlock-global main-signal main-signal-cv
+
+clean:
+	rm -f main-race main-deadlock main-deadlock-global main-signal main-signal-cv
+
+main-race: main-race.c mythreads.h
+	gcc -o main-race main-race.c $(FLAGS)
+
+main-deadlock: main-deadlock.c mythreads.h
+	gcc -o main-deadlock main-deadlock.c $(FLAGS)
+
+main-deadlock-global: main-deadlock-global.c mythreads.h
+	gcc -o main-deadlock-global main-deadlock-global.c $(FLAGS)
+
+main-signal: main-signal.c mythreads.h
+	gcc -o main-signal main-signal.c $(FLAGS)
+
+main-signal-cv: main-signal-cv.c mythreads.h
+	gcc -o main-signal-cv main-signal-cv.c $(FLAGS)
+

hw8/simu1/QUESTIONS.md

@@ -0,0 +1,66 @@
+# QUESTIONS: Thread Real Posix API
+
+In this section, we’ll write some simple multi-threaded programs and use a
+specific tool, called helgrind, to find problems in these programs.
+
+Read the README in the homework download for details on how to build the
+programs and run helgrind.
+
+## Questions
+
+Do not copy/paste all output of valgrind, only the parts, where your answers
+rely on. Run your tests on the bsys container (not your notebook!).
+
+1.  First build `main-race.c`. Examine the code so you can see the (hopefully
+    obvious) data race in the code. Now run helgrind (by typing **valgrind
+    \--tool=helgrind main-race**) to see how it reports the race. Does it point to
+    the right lines of code? What other information does it give to you?
+
+1.  Correkt your code:
+
+    1. What happens when you remove one of the offending lines of code?
+
+    1. Now add a lock around one of the updates to the shared variable,
+
+    1. and then around both.
+
+    1. What does helgrind report in each (2.1, 2.2 and 2.3) of these cases? 
+
+    Checkin your corrected file `main-race.`
+
+1.  Now let’s look at `main-deadlock.c`. Examine the code. This code has a
+    problem known as deadlock (which we discuss in much more depth in a
+    forthcoming chapter). Can you see what problem it might have? Does the
+    program run? Explain!
+
+1.  Now run helgrind on this code. What does helgrind report? Do not copy the
+    output into your answers, explain what helgrind tells you!
+
+1.  Now run helgrind on `main-deadlock-global.c`. 
+
+    1. Examine the code; does it have the same problem that `main-deadlock.c`
+    has?
+
+    1. Run the program. 
+
+    1. Should helgrind be reporting the same error? 
+
+    1. What does this tell you about tools like helgrind?
+
+1.  Let’s next look at `main-signal.c`. This code uses a variable (done) to
+    signal that the child is done and that the parent can now continue. Why is
+    this code inefficient? (what does the parent end up spending its time doing,
+    particularly if the child thread takes a long time to complete?)
+
+1.  Now run helgrind on this program. 
+    1.  What does it report? 
+    1.  Is the code correct?
+
+1.  Now look at a slightly modified version of the code, which is found in
+    `main-signal-cv.c`. This version uses a condition variable to do the
+    signaling (and associated lock). 
+
+     1. Why is this code preferred to the previous version? 
+     1. Is it correctness, or performance, or both?
+
+1.  Once again run helgrind on **main-signal-cv**. Does it report any errors?

hw8/simu1/README.md

@@ -0,0 +1,37 @@
+# README Synchronisation: Real POSIX API
+
+In this homework, you'll use a real tool on Linux to find problems in
+multi-threaded code. The tool is called **helgrind** (available as part of the
+valgrind suite of debugging tools).
+
+See <http://valgrind.org/docs/manual/hg-manual.html> for details about the tool,
+including how to download and install it (if it's not already on your Linux
+system).
+
+You'll then look at a number of multi-threaded C programs to see how you can
+use the tool to debug problematic threaded code.
+
+Then, type **make** to build all the different programs. Examine the Makefile
+for more details on how that works.
+
+Then, you have a few different C programs to look at:
+
+-   `main-race.c`:
+    A simple race condition
+
+-   `main-deadlock.c`:
+    A simple deadlock
+
+-   `main-deadlock-global.c`:
+    A solution to the deadlock problem
+
+-   `main-signal.c`:
+    A simple child/parent signaling example
+
+-   `main-signal-cv.c`:
+    A more efficient signaling via condition variables
+
+-   `mythreads.h`:
+    Header file with wrappers to make code check errors and be more readable
+
+With these programs, you can now answer the questions in the textbook.

hw8/simu1/main-deadlock-global.c

@@ -0,0 +1,31 @@
+#include <stdio.h>
+
+#include "mythreads.h"
+
+pthread_mutex_t g = PTHREAD_MUTEX_INITIALIZER;
+pthread_mutex_t m1 = PTHREAD_MUTEX_INITIALIZER;
+pthread_mutex_t m2 = PTHREAD_MUTEX_INITIALIZER;
+
+void* worker(void* arg) {
+    Pthread_mutex_lock(&g);
+    if ((long long) arg == 0) {
+	Pthread_mutex_lock(&m1);
+	Pthread_mutex_lock(&m2);
+    } else {
+	Pthread_mutex_lock(&m2);
+	Pthread_mutex_lock(&m1);
+    }
+    Pthread_mutex_unlock(&m1);
+    Pthread_mutex_unlock(&m2);
+    Pthread_mutex_unlock(&g);
+    return NULL;
+}
+
+int main(int argc, char *argv[]) {
+    pthread_t p1, p2;
+    Pthread_create(&p1, NULL, worker, (void *) (long long) 0);
+    Pthread_create(&p2, NULL, worker, (void *) (long long) 1);
+    Pthread_join(p1, NULL);
+    Pthread_join(p2, NULL);
+    return 0;
+}

hw8/simu1/main-deadlock.c

@@ -0,0 +1,28 @@
+#include <stdio.h>
+
+#include "mythreads.h"
+
+pthread_mutex_t m1 = PTHREAD_MUTEX_INITIALIZER;
+pthread_mutex_t m2 = PTHREAD_MUTEX_INITIALIZER;
+
+void* worker(void* arg) {
+    if ((long long) arg == 0) {
+	Pthread_mutex_lock(&m1);
+	Pthread_mutex_lock(&m2);
+    } else {
+	Pthread_mutex_lock(&m2);
+	Pthread_mutex_lock(&m1);
+    }
+    Pthread_mutex_unlock(&m1);
+    Pthread_mutex_unlock(&m2);
+    return NULL;
+}
+
+int main(int argc, char *argv[]) {
+    pthread_t p1, p2;
+    Pthread_create(&p1, NULL, worker, (void *) (long long) 0);
+    Pthread_create(&p2, NULL, worker, (void *) (long long) 1);
+    Pthread_join(p1, NULL);
+    Pthread_join(p2, NULL);
+    return 0;
+}

hw8/simu1/main-race.c

@@ -0,0 +1,18 @@
+#include <stdio.h>
+
+#include "mythreads.h"
+
+int balance = 0;
+
+void* worker(void* arg) {
+    balance++; // unprotected access
+    return NULL;
+}
+
+int main(int argc, char *argv[]) {
+    pthread_t p;
+    Pthread_create(&p, NULL, worker, NULL);
+    balance++; // unprotected access
+    Pthread_join(p, NULL);
+    return 0;
+}

hw8/simu1/main-signal-cv.c

@@ -0,0 +1,55 @@
+#include <stdio.h>
+
+#include "mythreads.h"
+
+// 
+// simple synchronizer: allows one thread to wait for another
+// structure "synchronizer_t" has all the needed data
+// methods are:
+//   init (called by one thread)
+//   wait (to wait for a thread)
+//   done (to indicate thread is done)
+// 
+typedef struct __synchronizer_t {
+    pthread_mutex_t lock;
+    pthread_cond_t cond;
+    int done;
+} synchronizer_t;
+
+synchronizer_t s;
+
+void signal_init(synchronizer_t *s) {
+    Pthread_mutex_init(&s->lock, NULL);
+    Pthread_cond_init(&s->cond, NULL);
+    s->done = 0;
+}
+
+void signal_done(synchronizer_t *s) {
+    Pthread_mutex_lock(&s->lock);
+    s->done = 1;
+    Pthread_cond_signal(&s->cond);
+    Pthread_mutex_unlock(&s->lock);
+}
+
+void signal_wait(synchronizer_t *s) {
+    Pthread_mutex_lock(&s->lock);
+    while (s->done == 0)
+	Pthread_cond_wait(&s->cond, &s->lock);
+    Pthread_mutex_unlock(&s->lock);
+}
+
+void* worker(void* arg) {
+    printf("this should print first\n");
+    signal_done(&s);
+    return NULL;
+}
+
+int main(int argc, char *argv[]) {
+    pthread_t p;
+    signal_init(&s);
+    Pthread_create(&p, NULL, worker, NULL);
+    signal_wait(&s);
+    printf("this should print last\n");
+
+    return 0;
+}

hw8/simu1/main-signal.c

@@ -0,0 +1,20 @@
+#include <stdio.h>
+
+#include "mythreads.h"
+
+int done = 0;
+
+void* worker(void* arg) {
+    printf("this should print first\n");
+    done = 1;
+    return NULL;
+}
+
+int main(int argc, char *argv[]) {
+    pthread_t p;
+    Pthread_create(&p, NULL, worker, NULL);
+    while (done == 0)
+	;
+    printf("this should print last\n");
+    return 0;
+}

hw8/simu1/mythreads.h

@@ -0,0 +1,62 @@
+#ifndef __MYTHREADS_h__
+#define __MYTHREADS_h__
+
+#include <pthread.h>
+#include <assert.h>
+#include <stdlib.h>
+#include <sys/time.h>
+
+double Time_GetSeconds() {
+    struct timeval t;
+    int rc = gettimeofday(&t, NULL);
+    assert(rc == 0);
+    return (double) ((double)t.tv_sec + (double)t.tv_usec / 1e6);
+}
+
+void Pthread_mutex_init(pthread_mutex_t *mutex,
+                        const pthread_mutexattr_t *attr) {
+    int rc = pthread_mutex_init(mutex, attr);
+    assert(rc == 0);
+}
+
+void Pthread_mutex_lock(pthread_mutex_t *m) {
+    int rc = pthread_mutex_lock(m);
+    assert(rc == 0);
+}
+
+void Pthread_mutex_unlock(pthread_mutex_t *m) {
+    int rc = pthread_mutex_unlock(m);
+    assert(rc == 0);
+}
+
+void Pthread_cond_init(pthread_cond_t *cond,
+		       const pthread_condattr_t *attr) {
+    int rc = pthread_cond_init(cond, attr);
+    assert(rc == 0);
+}
+
+void Pthread_cond_wait(pthread_cond_t *cond,
+		       pthread_mutex_t *mutex) {
+    int rc = pthread_cond_wait(cond, mutex);
+    assert(rc == 0);
+}
+
+void Pthread_cond_signal(pthread_cond_t *cond) {
+    int rc = pthread_cond_signal(cond);
+    assert(rc == 0);
+}
+
+void Pthread_create(pthread_t *thread, const pthread_attr_t *attr,
+                    void *(*start_routine)(void*), void *arg) {
+    int rc = pthread_create(thread, attr, start_routine, arg);
+    assert(rc == 0);
+}
+
+void Pthread_join(pthread_t thread, void **value_ptr) {
+    int rc = pthread_join(thread, value_ptr);
+    assert(rc == 0);
+}
+
+
+
+#endif // __MYTHREADS_h__

hw8/simu2/Makefile

@@ -0,0 +1,24 @@
+
+BINARIES = main-two-cvs-while main-two-cvs-if main-one-cv-while main-two-cvs-while-extra-unlock
+HEADERS = mythreads.h main-header.h main-common.c pc-header.h
+
+CC=gcc -Werror
+
+all: $(BINARIES)
+
+clean:
+	rm -f $(BINARIES)
+
+main-one-cv-while: main-one-cv-while.c $(HEADERS)
+	$(CC) -o main-one-cv-while main-one-cv-while.c -Wall -pthread
+
+main-two-cvs-if: main-two-cvs-if.c $(HEADERS)
+	$(CC) -o main-two-cvs-if main-two-cvs-if.c -Wall -pthread
+
+main-two-cvs-while: main-two-cvs-while.c $(HEADERS)
+	$(CC) -o main-two-cvs-while main-two-cvs-while.c -Wall -pthread
+
+main-two-cvs-while-extra-unlock: main-two-cvs-while-extra-unlock.c $(HEADERS)
+	$(CC) -o main-two-cvs-while-extra-unlock main-two-cvs-while-extra-unlock.c -Wall -pthread
+
+

hw8/simu2/QUESTIONS.md

@@ -0,0 +1,108 @@
+# QUESTIONS Synchronisation: CV
+
+This homework lets you explore some real code that uses locks and condition
+variables to implement various forms of the producer/consumer queue discussed in
+the chapter. You’ll look at the real code, run it in various configurations, and
+use it to learn about what works and what doesn’t, as well as other intricacies.
+
+The different versions of the code correspond to different ways to “solve” the
+producer/consumer problem. Most are incorrect; one is correct. Read the chapter
+to learn more about what the producer/consumer problem is, and what the code
+generally does.
+
+The first step is to download the code and type make to build all the variants.
+You should see four:
+
+-   `main-one-cv-while.c`: The producer/consumer problem solved with a single
+    condition variable.
+
+-   `main-two-cvs-if.c`: Same but with two condition variables and using an if to
+    check whether to sleep.
+
+-   `main-two-cvs-while.c`: Same but with two condition variables and while to
+    check whether to sleep. This is the correct version.
+
+-   `main-two-cvs-while-extra-unlock.c`: Same but releasing the lock and then
+    reacquiring it around the fill and get routines.
+
+It’s also useful to look at `pc-header.h` which contains common code for all of
+these different main programs, and the Makefile so as to build the code
+properly.
+
+See the `README.md` for details on these programs.
+
+## Questions
+
+Please explain your answers, even if not asked for it. Try to think first about
+the question, then run the code. Remember, in the exam you can't run the code,
+but have to think about the question and finally answer it correctly.
+
+### Fix Source Code
+
+When you compile the programs on your workstation, you get a lot of warnings
+which are turned into errors. You have to correct these errors first. Check, by
+which parameters a thread is created, and how the id is casted later on.
+
+0.  Explain the problem, and how you fixed it.
+
+### `main-two-cvs-while.c`
+
+Our first questions focus on `main-two-cvs-while.c` (the working solution).
+First, study the code. Do you think you have an understanding of what should
+happen when you run the program?
+
+1.  Now run with one producer and one consumer, and have the producer produce a
+    few values. Start with a buffer of size 1, and then increase it. How does the
+    behavior of the code change when the buffer is larger? (or does it?)
+
+1.  What would you predict num full to be with different buffer sizes (e.g., -m
+    10) and different numbers of produced items (e.g., -l 100), when you change
+    the consumer sleep string from default (no sleep) to -C 0,0,0,0,0,0,1?
+
+1.  If possible, run the code on different systems (e.g., Mac OS X , Linux, lab
+    container and your notebook). Do you see different behavior across these
+    systems?
+
+1.  Let’s look at some timings of different runs. How long do you think the
+    following execution, with one producer, three consumers, a single-entry
+    shared buffer, and each consumer pausing at point c3 for a second, will take?
+
+      prompt> ./main-two-cvs-while -p 1 -c 3 -m 1 -C
+              0,0,0,1,0,0,0:0,0,0,1,0,0,0:0,0,0,1,0,0,0 -l 10 -v -t
+
+1.  Now change the size of the shared buffer to 3(-m3). Will this make any
+    difference in the total time?
+
+1.  Now change the location of the sleep to c6 (this models a consumer taking
+    something off the queue and then doing something with it for a while), again
+    using a single-entry buffer. What time do you predict in this case?
+
+    ```text
+     prompt> ./main-two-cvs-while -p 1 -c 3 -m 1 -C
+             0,0,0,0,0,0,1:0,0,0,0,0,0,1:0,0,0,0,0,0,1 -l 10 -v -t
+    ```
+
+1.  Finally, change the buffer size to 3 again (-m 3). What time do you predict
+    now?
+
+### `main-one-cv-while.c`
+
+1.  Now let’s look at `main-one-cv-while.c`. Can you configure a sleep string,
+    assuming a single producer, one consumer, and a buffer of size 1, to cause a
+    problem with this code? Explain why this happens!
+
+1.  Now change the number of consumers to two. Can you construct sleep strings
+    for the producer and the consumers so as to cause a problem in the code?
+    Explain why this happens!
+
+### `main-two-cvs-if.c`
+
+1.  Now examine `main-two-cvs-if.c`. Can you cause a problem to happen in this
+    code? Again consider the case where there is only one consumer, and then the
+    case where there is more than one. Explain the problematic code sequence. 
+
+### `main-two-cvs-while-extra-unlock.c`
+
+1.  Finally, examine `main-two-cvs-while-extra-unlock.c`. What problem arises
+    when you release the lock before doing a put or a get? Can you reliably cause
+    such a problem to happen, given the sleep strings? What bad thing can happen?

hw8/simu2/README.md

@@ -0,0 +1,237 @@
+# README Synchronisation: CV
+
+This homework lets you explore some real code that uses locks and condition
+variables to implement various forms of the producer/consumer queue discussed in
+the chapter. You'll look at the real code, run it in various configurations, and
+use it to learn about what works and what doesn't, as well as other intricacies.
+
+The different versions of the code correspond to different ways to "solve" the
+producer/consumer problem. Most are incorrect; one is correct.  Read the chapter
+to learn more about what the producer/consumer problem is, and what the code
+generally does.
+
+The first step is to download the code and type make to build all the variants.
+You should see four:
+
+-   `main-one-cv-while.c`: The producer/consumer problem solved with a single
+    condition variable.
+
+-   `main-two-cvs-if.c`: Same but with two condition variables and using an if to
+    check whether to sleep.
+
+-   `main-two-cvs-while.c`: Same but with two condition variables and while to
+    check whether to sleep. This is the correct version.
+
+-   `main-two-cvs-while-extra-unlock.c`: Same but releasing the lock and then
+    reacquiring it around the fill and get routines.
+
+It's also useful to look at `pc-header.h` which contains common code for all of
+these different main programs, and the Makefile so as to build the code
+properly.
+
+Each program takes the following flags:
+
+```text
+-l <number of items each producer produces>
+
+-m <size of the shared producer/consumer buffer>
+
+-p <number of producers>
+
+-c <number of consumers>
+
+-P <sleep string: how producer should sleep at various points>
+
+-C <sleep string: how consumer should sleep at various points>
+
+-v verbose flag: trace what is happening and print it]
+
+-t [timing flag: time entire execution and print total time]
+```
+
+The first four arguments are relatively self-explanatory: -l specifies how many
+times each producer should loop (and thus how many data items each producer
+produces), -m controls the size of the shared buffer (greater than or equal to
+one), and -p and -c set how many producers and consumers there are,
+respectively.
+
+What is more interesting are the two sleep strings, one for producers, and one
+for consumers. These flags allow you to make each thread sleep at certain points
+in an execution and thus switch to other threads; doing so allows you to play
+with each solution and perhaps pinpoint specific problems or study other facets
+of the producer/consumer problem.
+
+The string is specified as follows. If there are three producers, for example,
+the string should specify sleep times for each producer separately, with a colon
+separator. The sleep string for these three producers would look something like
+this:
+
+```text
+  sleep_string_for_p0:sleep_string_for_p1:sleep_string_for_p2
+```
+
+Each sleep string, in turn, is a comma-separated list, which is used to decide
+how much to sleep at each sleep point in the code. To understand this
+per-producer or per-consumer sleep string better, let's look at the code in
+`main-two-cvs-while.c`, specifically at the producer code. In this code snippet,
+a producer thread loops for a while, putting elements into the shared buffer via
+calls to do_fill(). Around this filling routine are some waiting and signaling
+code to ensure the buffer is not full when the producer tries to fill it. See
+the chapter for more details.
+
+```c
+void *producer(void *arg) {
+    int id = (int) arg;
+    int i;
+    for (i = 0; i < loops; i++) {   p0;
+        Mutex_lock(&m);             p1;
+        while (num_full == max) {   p2;
+            Cond_wait(&empty, &m);  p3;
+        }
+        do_fill(i);                 p4;
+        Cond_signal(&fill);         p5;
+        Mutex_unlock(&m);           p6;
+    }
+    return NULL;
+}
+```
+
+As you can see from the code, there are a number of points labeled p0, p1, etc.
+These points are where the code can be put to sleep. The consumer code (not
+shown here) has similar wait points (c0, etc.).
+
+Specifying a sleep string for a producer is easy: just identify how long the
+producer should sleep at each point p0, p1, ..., p6. For example, the string
+1,0,0,0,0,0,0 specifies that the producer should sleep for 1 second at marker p0
+(before grabbing the lock), and then not at all each time through the loop.
+
+Now let's show the output of running one of these programs.  To begin, let's
+assume that the user runs with just one producer and one consumer. Let's not add
+any sleeping at all (this is the default behavior). The buffer size, in this
+example, is set to 2 (-m 2).
+
+First, let's build the code:
+
+```text
+prompt> make
+gcc -o main-two-cvs-while main-two-cvs-while.c -Wall -pthread
+gcc -o main-two-cvs-if main-two-cvs-if.c -Wall -pthread
+gcc -o main-one-cv-while main-one-cv-while.c -Wall -pthread
+gcc -o main-two-cvs-while-extra-unlock main-two-cvs-while-extra-unlock.c
+  -Wall -pthread
+```
+
+Now we can run something:
+
+```text
+prompt> ./main-two-cvs-while -l 3 -m 2 -p 1 -c 1 -v
+```
+
+In this case, if you trace the code (with the verbose flag, -v), you will get
+the following output (or something like it) on the screen:
+
+```text
+ NF             P0 C0
+  0 [*---  --- ] p0
+  0 [*---  --- ]    c0
+  0 [*---  --- ] p1
+  1 [u  0 f--- ] p4
+  1 [u  0 f--- ] p5
+  1 [u  0 f--- ] p6
+  1 [u  0 f--- ] p0
+  1 [u  0 f--- ]    c1
+  0 [ --- *--- ]    c4
+  0 [ --- *--- ]    c5
+  0 [ --- *--- ]    c6
+  0 [ --- *--- ]    c0
+  0 [ --- *--- ] p1
+  1 [f--- u  1 ] p4
+  1 [f--- u  1 ] p5
+  1 [f--- u  1 ] p6
+  1 [f--- u  1 ] p0
+  1 [f--- u  1 ]    c1
+  0 [*---  --- ]    c4
+  0 [*---  --- ]    c5
+  0 [*---  --- ]    c6
+  0 [*---  --- ]    c0
+  0 [*---  --- ] p1
+  1 [u  2 f--- ] p4
+  1 [u  2 f--- ] p5
+  1 [u  2 f--- ] p6
+  1 [u  2 f--- ]    c1
+  0 [ --- *--- ]    c4
+  0 [ --- *--- ]    c5
+  0 [ --- *--- ]    c6
+  1 [f--- uEOS ] [main: added end-of-stream marker]
+  1 [f--- uEOS ]    c0
+  1 [f--- uEOS ]    c1
+  0 [*---  --- ]    c4
+  0 [*---  --- ]    c5
+  0 [*---  --- ]    c6
+
+Consumer consumption:
+  C0 -> 3
+```
+
+Before describing what is happening in this simple example, let's understand the
+depiction of the shared buffer in the output, as is shown on the left. At first
+it is empty (an empty slot indicated by ---, and the two empty slots shown as
+[*--- --- ]); the output also shows the number of entries in the buffer
+(num_full), which starts at 0. Then, after P0 puts a value in it, its state
+changes to [u 0 f--- ](<and num_full changes to 1>). You might also notice a few
+additional markers here; the u marker shows where the use_ptr is (this is where
+the next consumer to consume a value will get something from); similarly, the f
+marker shows where the fill_ptr is (this is where the next producer will
+produce a value). When you see the \* marker, it just means the use_ptr and
+fill_ptr are pointing to the same slot.
+
+Along the right you can see the trace of which step each producer and consumer
+is about to execute. For example, the producer grabs the lock (p1), and then,
+because the buffer has an empty slot, produces a value into it (p4). It then
+continues until the point where it releases the lock (p6) and then tries to
+reacquire it. In this example, the consumer acquires the lock instead and
+consumes the value (c1, c4). Study the trace further to understand how the
+producer/consumer solution works with a single producer and consumer.
+
+Now let's add some pauses to change the behavior of the trace. In this case,
+let's say we want to make the producer sleep so that the consumer can run first.
+We can accomplish this as follows:
+
+```text
+prompt> ./main-two-cvs-while -l 1 -m 2 -p 1 -c 1 -P 1,0,0,0,0,0,0 -C 0 -v
+```
+
+```text
+The results:
+ NF             P0 C0
+  0 [*---  --- ] p0
+  0 [*---  --- ]    c0
+  0 [*---  --- ]    c1
+  0 [*---  --- ]    c2
+  0 [*---  --- ] p1
+  1 [u  0 f--- ] p4
+  1 [u  0 f--- ] p5
+  1 [u  0 f--- ] p6
+  1 [u  0 f--- ] p0
+  1 [u  0 f--- ]    c3
+  0 [ --- *--- ]    c4
+  0 [ --- *--- ]    c5
+  0 [ --- *--- ]    c6
+  0 [ --- *--- ]    c0
+  0 [ --- *--- ]    c1
+  0 [ --- *--- ]    c2
+ ...
+```
+
+As you can see, the producer hits the p0 marker in the code and then grabs the
+first value from its sleep specification, which in this case is 1, and thus each
+sleeps for 1 second before even trying to grab the lock. Thus, the consumer gets
+to run, grabs the lock, but finds the queue empty, and thus sleeps (releasing
+the lock). The producer then runs (eventually), and all proceeds as you might
+expect.
+
+Do note: a sleep specification must be given for each producer and consumer.
+Thus, if you create two producers and three consumers (with -p 2 -c 3, you must
+specify sleep strings for each (e.g., -P 0:1 or -C 0,1,2:0:3,3,3,1,1,1). Sleep
+strings can be shorter than the number of sleep points in the code; the
+remaining sleep slots are initialized to be zero.

hw8/simu2/main-common.c

@@ -0,0 +1,136 @@
+// Common usage() prints out stuff for command-line help
+void usage() {
+    fprintf(stderr, "usage: \n");
+    fprintf(stderr, "  -l <number of items each producer produces>\n");
+    fprintf(stderr, "  -m <size of the shared producer/consumer buffer>\n");
+    fprintf(stderr, "  -p <number of producers>\n");
+    fprintf(stderr, "  -c <number of consumers>\n");
+    fprintf(stderr, "  -P <sleep string: how each producer should sleep at various points in execution>\n");
+    fprintf(stderr, "  -C <sleep string: how each consumer should sleep at various points in execution>\n");
+    fprintf(stderr, "  -v [ verbose flag: trace what is happening and print it ]\n");
+    fprintf(stderr, "  -t [ timing flag: time entire execution and print total time ]\n");
+    exit(1);
+}
+
+// Common main() for all four programs
+// - Does arg parsing
+// - Starts producers and consumers
+// - Once producers are finished, puts END_OF_STREAM
+//   marker into shared queue to signal end to consumers
+// - Then waits for consumers and prints some final info
+int main(int argc, char *argv[]) {
+    loops = 1;
+    max = 1;
+    consumers = 1;
+    producers = 1;
+
+    char *producer_pause_string = NULL;
+    char *consumer_pause_string = NULL;
+
+    opterr = 0;
+    int c;
+    while ((c = getopt (argc, argv, "l:m:p:c:P:C:vt")) != -1) {
+	switch (c) {
+	case 'l':
+	    loops = atoi(optarg);
+	    break;
+	case 'm':
+	    max = atoi(optarg);
+	    break;
+	case 'p':
+	    producers = atoi(optarg);
+	    break;
+	case 'c':
+	    consumers = atoi(optarg);
+	    break;
+	case 'P':
+	    producer_pause_string = optarg;
+	    break;
+	case 'C':
+	    consumer_pause_string = optarg;
+	    break;
+	case 'v':
+	    do_trace = 1;
+	    break;
+	case 't':
+	    do_timing = 1;
+	    break;
+	default:
+	    usage();
+	}
+    }
+
+    assert(loops > 0);
+    assert(max > 0);
+    assert(producers <= MAX_THREADS);
+    assert(consumers <= MAX_THREADS);
+
+    if (producer_pause_string != NULL)
+	parse_pause_string(producer_pause_string, "producers", producers, producer_pause_times);
+    if (consumer_pause_string != NULL) 
+	parse_pause_string(consumer_pause_string, "consumers", consumers, consumer_pause_times);
+
+    // make space for shared buffer, and init it ...
+    buffer = (int *) Malloc(max * sizeof(int));
+    int i;
+    for (i = 0; i < max; i++) {
+	buffer[i] = EMPTY;
+    }
+
+    do_print_headers();
+
+    double t1 = Time_GetSeconds();
+
+    // start up all threads; order doesn't matter here
+    pthread_t pid[MAX_THREADS], cid[MAX_THREADS];
+    int thread_id = 0;
+    for (i = 0; i < producers; i++) {
+	Pthread_create(&pid[i], NULL, producer, (void *) (long long) thread_id); 
+	thread_id++;
+    }
+    for (i = 0; i < consumers; i++) {
+	Pthread_create(&cid[i], NULL, consumer, (void *) (long long) thread_id); 
+	thread_id++;
+    }
+
+    // now wait for all PRODUCERS to finish
+    for (i = 0; i < producers; i++) {
+	Pthread_join(pid[i], NULL); 
+    }
+
+    // end case: when producers are all done
+    // - put "consumers" number of END_OF_STREAM's in queue
+    // - when consumer sees -1, it exits
+    for (i = 0; i < consumers; i++) {
+	Mutex_lock(&m);
+	while (num_full == max) 
+	    Cond_wait(empty_cv, &m);
+	do_fill(END_OF_STREAM);
+	do_eos();
+	Cond_signal(fill_cv);
+	Mutex_unlock(&m);
+    }
+
+    // now OK to wait for all consumers
+    int counts[consumers];
+    for (i = 0; i < consumers; i++) {
+	Pthread_join(cid[i], (void *) &counts[i]); 
+    }
+
+    double t2 = Time_GetSeconds();
+
+    if (do_trace) {
+	printf("\nConsumer consumption:\n");
+	for (i = 0; i < consumers; i++) {
+	    printf("  C%d -> %d\n", i, counts[i]);
+	}
+	printf("\n");
+    }
+
+    if (do_timing) {
+	printf("Total time: %.2f seconds\n", t2-t1);
+    }
+
+    return 0;
+}
+

hw8/simu2/main-header.h

@@ -0,0 +1,171 @@
+#ifndef __main_header_h__
+#define __main_header_h__
+
+// all this is for the homework side of things
+
+int do_trace = 0;
+int do_timing = 0;
+
+#define p0 do_pause(id, 1, 0, "p0"); 
+#define p1 do_pause(id, 1, 1, "p1"); 
+#define p2 do_pause(id, 1, 2, "p2"); 
+#define p3 do_pause(id, 1, 3, "p3"); 
+#define p4 do_pause(id, 1, 4, "p4"); 
+#define p5 do_pause(id, 1, 5, "p5"); 
+#define p6 do_pause(id, 1, 6, "p6"); 
+
+#define c0 do_pause(id, 0, 0, "c0"); 
+#define c1 do_pause(id, 0, 1, "c1"); 
+#define c2 do_pause(id, 0, 2, "c2"); 
+#define c3 do_pause(id, 0, 3, "c3"); 
+#define c4 do_pause(id, 0, 4, "c4"); 
+#define c5 do_pause(id, 0, 5, "c5"); 
+#define c6 do_pause(id, 0, 6, "c6"); 
+
+int producer_pause_times[MAX_THREADS][7];
+int consumer_pause_times[MAX_THREADS][7];
+
+// needed to avoid interleaving of print out from threads
+pthread_mutex_t print_lock = PTHREAD_MUTEX_INITIALIZER;
+
+void do_print_headers() {
+    if (do_trace == 0) 
+	return;
+    int i;
+    printf("%3s ", "NF");
+    for (i = 0; i < max; i++) {
+	printf(" %3s ", "   ");
+    }
+    printf("  ");
+
+    for (i = 0; i < producers; i++) 
+	printf("P%d ", i);
+    for (i = 0; i < consumers; i++) 
+	printf("C%d ", i);
+    printf("\n");
+}
+
+void do_print_pointers(int index) {
+    if (use_ptr == index && fill_ptr == index) {
+	printf("*");
+    } else if (use_ptr == index) {
+	printf("u");
+    } else if (fill_ptr == index) {
+	printf("f");
+    } else {
+	printf(" ");
+    }
+}
+
+void do_print_buffer() {
+    int i;
+    printf("%3d [", num_full);
+    for (i = 0; i < max; i++) {
+	do_print_pointers(i);
+	if (buffer[i] == EMPTY) {
+	    printf("%3s ", "---");
+	} else if (buffer[i] == END_OF_STREAM) {
+	    printf("%3s ", "EOS");
+	} else {
+	    printf("%3d ", buffer[i]);
+	}
+    }
+    printf("] ");
+}
+
+void do_eos() {
+    if (do_trace) {
+	Mutex_lock(&print_lock);
+	do_print_buffer();
+	//printf("%3d [added end-of-stream marker]\n", num_full);
+	printf("[main: added end-of-stream marker]\n");
+	Mutex_unlock(&print_lock);
+    }
+}
+
+void do_pause(int thread_id, int is_producer, int pause_slot, char *str) {
+    int i;
+    if (do_trace) {
+	Mutex_lock(&print_lock);
+	do_print_buffer();
+
+	// skip over other thread's spots
+	for (i = 0; i < thread_id; i++) {
+	    printf("   ");
+	}
+	printf("%s\n", str);
+	Mutex_unlock(&print_lock);
+    }
+
+    int local_id = thread_id;
+    int pause_time;
+    if (is_producer) {
+	pause_time = producer_pause_times[local_id][pause_slot];
+    } else {
+	local_id = thread_id - producers;
+	pause_time = consumer_pause_times[local_id][pause_slot];
+    }
+    // printf(" PAUSE %d\n", pause_time);
+    sleep(pause_time);
+}
+
+void ensure(int expression, char *msg) {
+    if (expression == 0) {
+	fprintf(stderr, "%s\n", msg);
+	exit(1);
+    }
+}
+
+void parse_pause_string(char *str, char *name, int expected_pieces, 
+			int pause_array[MAX_THREADS][7]) {
+
+    // string looks like this (or should):
+    //   1,2,0:2,3,4,5
+    //   n-1 colons if there are n producers/consumers
+    //   comma-separated for sleep amounts per producer or consumer
+    int index = 0;
+
+    char *copy_entire = strdup(str);
+    char *outer_marker;
+    int colon_count = 0;
+    char *p = strtok_r(copy_entire, ":", &outer_marker);
+    while (p) {
+	// init array: default sleep is 0
+	int i;
+	for (i = 0; i < 7; i++)  
+	    pause_array[index][i] = 0;
+
+	// for each piece, comma separated
+	char *inner_marker;
+	char *copy_piece = strdup(p);
+	char *c = strtok_r(copy_piece, ",", &inner_marker);
+	int comma_count = 0;
+
+	int inner_index = 0;
+	while (c) {
+	    int pause_amount = atoi(c);
+	    ensure(inner_index < 7, "you specified a sleep string incorrectly... (too many comma-separated args)");
+	    // printf("setting %s pause %d to %d\n", name, inner_index, pause_amount);
+	    pause_array[index][inner_index] = pause_amount;
+	    inner_index++;
+
+	    c = strtok_r(NULL, ",", &inner_marker);	
+	    comma_count++;
+	}
+	free(copy_piece);
+	index++;
+
+	// continue with colon separated list
+	p = strtok_r(NULL, ":", &outer_marker);
+	colon_count++;
+    }
+
+    free(copy_entire);
+    if (expected_pieces != colon_count) {
+	fprintf(stderr, "Error: expected %d %s in sleep specification, got %d\n", expected_pieces, name, colon_count);
+	exit(1);
+    }
+}
+
+
+#endif // __main_header_h__

hw8/simu2/main-one-cv-while.c

@@ -0,0 +1,79 @@
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <assert.h>
+#include <pthread.h>
+#include <sys/time.h>
+#include <string.h>
+
+#include "mythreads.h"
+
+#include "pc-header.h"
+
+pthread_cond_t cv = PTHREAD_COND_INITIALIZER;
+pthread_mutex_t m = PTHREAD_MUTEX_INITIALIZER;
+
+#include "main-header.h"
+
+void do_fill(int value) {
+    // ensure empty before usage
+    ensure(buffer[fill_ptr] == EMPTY, "error: tried to fill a non-empty buffer");
+    buffer[fill_ptr] = value;
+    fill_ptr = (fill_ptr + 1) % max;
+    num_full++;
+}
+
+int do_get() {
+    int tmp = buffer[use_ptr];
+    ensure(tmp != EMPTY, "error: tried to get an empty buffer");
+    buffer[use_ptr] = EMPTY; 
+    use_ptr = (use_ptr + 1) % max;
+    num_full--;
+    return tmp;
+}
+
+void *producer(void *arg) {
+    int id = (int) arg;
+    // make sure each producer produces unique values
+    int base = id * loops; 
+    int i;
+    for (i = 0; i < loops; i++) {   p0;
+	Mutex_lock(&m);             p1;
+	while (num_full == max) {   p2;
+	    Cond_wait(&cv, &m);     p3;
+	}
+	do_fill(base + i);          p4;
+	Cond_signal(&cv);           p5;
+	Mutex_unlock(&m);           p6;
+    }
+    return NULL;
+}
+                                                                               
+void *consumer(void *arg) {
+    int id = (int) arg;
+    int tmp = 0;
+    int consumed_count = 0;
+    while (tmp != END_OF_STREAM) { c0;
+	Mutex_lock(&m);            c1;
+	while (num_full == 0) {    c2;
+	    Cond_wait(&cv, &m);    c3;
+        }
+	tmp = do_get();            c4;
+	Cond_signal(&cv);          c5;
+	Mutex_unlock(&m);          c6;
+	consumed_count++;
+    }
+
+    // return consumer_count-1 because END_OF_STREAM does not count
+    return (void *) (long long) (consumed_count - 1);
+}
+
+// must set these appropriately to use "main-common.c"
+pthread_cond_t *fill_cv = &cv;
+pthread_cond_t *empty_cv = &cv;
+
+// all codes use this common base to start producers/consumers
+// and all the other related stuff
+#include "main-common.c"
+

hw8/simu2/main-two-cvs-if.c

@@ -0,0 +1,80 @@
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <assert.h>
+#include <pthread.h>
+#include <sys/time.h>
+#include <string.h>
+
+#include "mythreads.h"
+#include "pc-header.h"
+
+pthread_cond_t empty  = PTHREAD_COND_INITIALIZER;
+pthread_cond_t fill   = PTHREAD_COND_INITIALIZER;
+pthread_mutex_t m     = PTHREAD_MUTEX_INITIALIZER;
+
+#include "main-header.h"
+
+void do_fill(int value) {
+    // ensure empty before usage
+    ensure(buffer[fill_ptr] == EMPTY, "error: tried to fill a non-empty buffer");
+    buffer[fill_ptr] = value;
+    fill_ptr = (fill_ptr + 1) % max;
+    num_full++;
+}
+
+int do_get() {
+    int tmp = buffer[use_ptr];
+    ensure(tmp != EMPTY, "error: tried to get an empty buffer");
+    buffer[use_ptr] = EMPTY; 
+    use_ptr = (use_ptr + 1) % max;
+    num_full--;
+    return tmp;
+}
+
+void *producer(void *arg) {
+    int id = (int) arg;
+    // make sure each producer produces unique values
+    int base = id * loops; 
+    int i;
+    for (i = 0; i < loops; i++) {   p0;
+	Mutex_lock(&m);             p1;
+	if (num_full == max) {      p2;
+	    Cond_wait(&empty, &m);  p3;
+	}
+	do_fill(base + i);          p4;
+	Cond_signal(&fill);         p5;
+	Mutex_unlock(&m);           p6;
+    }
+    return NULL;
+}
+                                                                               
+void *consumer(void *arg) {
+    int id = (int) arg;
+    int tmp = 0;
+    int consumed_count = 0;
+    while (tmp != END_OF_STREAM) { c0;
+	Mutex_lock(&m);            c1;
+	if (num_full == 0) {       c2;
+	    Cond_wait(&fill, &m);  c3;
+        }
+	tmp = do_get();            c4;
+	Cond_signal(&empty);       c5;
+	Mutex_unlock(&m);          c6;
+	consumed_count++;
+    }
+
+    // return consumer_count-1 because END_OF_STREAM does not count
+    return (void *) (long long) (consumed_count - 1);
+}
+
+// must set these appropriately to use "main-common.c"
+pthread_cond_t *fill_cv = &fill;
+pthread_cond_t *empty_cv = &empty;
+
+// all codes use this common base to start producers/consumers
+// and all the other related stuff
+#include "main-common.c"
+
+

hw8/simu2/main-two-cvs-while-extra-unlock.c

@@ -0,0 +1,84 @@
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <assert.h>
+#include <pthread.h>
+#include <sys/time.h>
+#include <string.h>
+
+#include "mythreads.h"
+
+#include "pc-header.h"
+
+pthread_cond_t empty  = PTHREAD_COND_INITIALIZER;
+pthread_cond_t fill   = PTHREAD_COND_INITIALIZER;
+pthread_mutex_t m     = PTHREAD_MUTEX_INITIALIZER;
+
+#include "main-header.h"
+
+void do_fill(int value) {
+    // ensure empty before usage
+    ensure(buffer[fill_ptr] == EMPTY, "error: tried to fill a non-empty buffer");
+    buffer[fill_ptr] = value;
+    fill_ptr = (fill_ptr + 1) % max;
+    num_full++;
+}
+
+int do_get() {
+    int tmp = buffer[use_ptr];
+    ensure(tmp != EMPTY, "error: tried to get an empty buffer");
+    buffer[use_ptr] = EMPTY; 
+    use_ptr = (use_ptr + 1) % max;
+    num_full--;
+    return tmp;
+}
+
+void *producer(void *arg) {
+    int id = (int) arg;
+    // make sure each producer produces unique values
+    int base = id * loops; 
+    int i;
+    for (i = 0; i < loops; i++) {   p0;
+	Mutex_lock(&m);             p1;
+	while (num_full == max) {   p2;
+	    Cond_wait(&empty, &m);  p3;
+	}
+	Mutex_unlock(&m);
+	do_fill(base + i);          p4;
+	Mutex_lock(&m);
+	Cond_signal(&fill);         p5;
+	Mutex_unlock(&m);           p6;
+    }
+    return NULL;
+}
+                                                                               
+void *consumer(void *arg) {
+    int id = (int) arg;
+    int tmp = 0;
+    int consumed_count = 0;
+    while (tmp != END_OF_STREAM) { c0;
+	Mutex_lock(&m);            c1;
+	while (num_full == 0) {    c2;
+	    Cond_wait(&fill, &m);  c3;
+        }
+	Mutex_unlock(&m);
+	tmp = do_get();            c4;
+	Mutex_lock(&m);
+	Cond_signal(&empty);       c5;
+	Mutex_unlock(&m);          c6;
+	consumed_count++;
+    }
+
+    // return consumer_count-1 because END_OF_STREAM does not count
+    return (void *) (long long) (consumed_count - 1);
+}
+
+// must set these appropriately to use "main-common.c"
+pthread_cond_t *fill_cv = &fill;
+pthread_cond_t *empty_cv = &empty;
+
+// all codes use this common base to start producers/consumers
+// and all the other related stuff
+#include "main-common.c"
+

hw8/simu2/main-two-cvs-while.c

@@ -0,0 +1,83 @@
+#include <ctype.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <assert.h>
+#include <pthread.h>
+#include <sys/time.h>
+#include <string.h>
+
+#include "mythreads.h"
+
+#include "pc-header.h"
+
+// used in producer/consumer signaling protocol
+pthread_cond_t empty  = PTHREAD_COND_INITIALIZER;
+pthread_cond_t fill   = PTHREAD_COND_INITIALIZER;
+pthread_mutex_t m     = PTHREAD_MUTEX_INITIALIZER;
+
+#include "main-header.h"
+
+void do_fill(int value) {
+    // ensure empty before usage
+    ensure(buffer[fill_ptr] == EMPTY, "error: tried to fill a non-empty buffer");
+    buffer[fill_ptr] = value;
+    fill_ptr = (fill_ptr + 1) % max;
+    num_full++;
+}
+
+int do_get() {
+    int tmp = buffer[use_ptr];
+    ensure(tmp != EMPTY, "error: tried to get an empty buffer");
+    buffer[use_ptr] = EMPTY; 
+    use_ptr = (use_ptr + 1) % max;
+    num_full--;
+    return tmp;
+}
+
+void *producer(void *arg) {
+    int id = (int) arg;
+    // make sure each producer produces unique values
+    int base = id * loops; 
+    int i;
+    for (i = 0; i < loops; i++) {   p0;
+	Mutex_lock(&m);             p1;
+	while (num_full == max) {   p2;
+	    Cond_wait(&empty, &m);  p3;
+	}
+	do_fill(base + i);          p4;
+	Cond_signal(&fill);         p5;
+	Mutex_unlock(&m);           p6;
+    }
+    return NULL;
+}
+                                                                               
+void *consumer(void *arg) {
+    int id = (int) arg;
+    int tmp = 0;
+    int consumed_count = 0;
+    while (tmp != END_OF_STREAM) { c0;
+	Mutex_lock(&m);            c1;
+	while (num_full == 0) {    c2;
+	    Cond_wait(&fill, &m);  c3;
+        }
+	tmp = do_get();            c4;
+	Cond_signal(&empty);       c5;
+	Mutex_unlock(&m);          c6;
+	consumed_count++;
+    }
+
+    // return consumer_count-1 because END_OF_STREAM does not count
+    return (void *) (long long) (consumed_count - 1);
+}
+
+// must set these appropriately to use "main-common.c"
+pthread_cond_t *fill_cv = &fill;
+pthread_cond_t *empty_cv = &empty;
+
+// all codes use this common base to start producers/consumers
+// and all the other related stuff
+#include "main-common.c"
+
+
+

hw8/simu2/mythreads.h

@@ -0,0 +1,69 @@
+#ifndef __MYTHREADS_h__
+#define __MYTHREADS_h__
+
+#include <pthread.h>
+#include <assert.h>
+#include <sys/time.h>
+#include <stdlib.h>
+
+void *Malloc(size_t size) {
+    void *p = malloc(size);
+    assert(p != NULL);
+    return p;
+}
+
+double Time_GetSeconds() {
+    struct timeval t;
+    int rc = gettimeofday(&t, NULL);
+    assert(rc == 0);
+    return (double) ((double)t.tv_sec + (double)t.tv_usec / 1e6);
+}
+
+void work(int seconds) {
+    double t0 = Time_GetSeconds();
+    while ((Time_GetSeconds() - t0) < (double)seconds)
+	;
+}
+
+void Mutex_init(pthread_mutex_t *m) {
+    assert(pthread_mutex_init(m, NULL) == 0);
+}
+
+void Mutex_lock(pthread_mutex_t *m) {
+    int rc = pthread_mutex_lock(m);
+    assert(rc == 0);
+}
+
+void Mutex_unlock(pthread_mutex_t *m) {
+    int rc = pthread_mutex_unlock(m);
+    assert(rc == 0);
+}
+
+void Cond_init(pthread_cond_t *c) {
+    assert(pthread_cond_init(c, NULL) == 0);
+}
+
+void Cond_wait(pthread_cond_t *c, pthread_mutex_t *m) {
+    int rc = pthread_cond_wait(c, m);
+    assert(rc == 0);
+}
+
+void Cond_signal(pthread_cond_t *c) {
+    int rc = pthread_cond_signal(c);
+    assert(rc == 0);
+}
+
+
+void Pthread_create(pthread_t *thread, const pthread_attr_t *attr, 	
+		    void *(*start_routine)(void*), void *arg) {
+    int rc = pthread_create(thread, attr, start_routine, arg);
+    assert(rc == 0);
+}
+
+void Pthread_join(pthread_t thread, void **value_ptr) {
+    int rc = pthread_join(thread, value_ptr);
+    assert(rc == 0);
+}
+
+
+#endif // __MYTHREADS_h__

hw8/simu2/pc-header.h

@@ -0,0 +1,22 @@
+#ifndef __pc_header_h__
+#define __pc_header_h__
+
+#define MAX_THREADS (100)  // maximum number of producers/consumers
+
+int producers = 1;         // number of producers
+int consumers = 1;         // number of consumers
+
+int *buffer;               // the buffer itself: malloc in main()
+int max;                   // size of the producer/consumer buffer
+
+int use_ptr  = 0;          // tracks where next consume should come from
+int fill_ptr = 0;          // tracks where next produce should go to
+int num_full = 0;          // counts how many entries are full
+
+int loops;                 // number of items that each producer produces
+
+#define EMPTY         (-2) // buffer slot has nothing in it
+#define END_OF_STREAM (-1) // consumer who grabs this should exit
+
+#endif // __pc_header_h__
+ 

hw8/task1/README.md

@@ -0,0 +1,258 @@
+# Homework hw8 task1
+
+-   ['Proof-of-Work' als Bibliothek](#proof-of-work-als-bibliothek)
+    -   [Idiomatischer Code](#idiomatischer-code)
+    -   [`ANSWERS.md`](#answersmd)
+-   [Implementierung](#implementierung)
+    -   [Parameter _threads_](#parameter-threads)
+    -   [Flag _verbose_](#flag-verbose)
+    -   [Suchen mit mehreren Threads](#suchen-mit-mehreren-threads)
+        -   [-s Flag](#s-flag)
+        -   [-w Flag](#w-flag)
+        -   [Weitere Options](#weitere-options)
+        -   [-help Ausgabe](#help-ausgabe)
+    -   [Command timings](#command-timings)
+    -   [Tests](#tests)
+    -   [Laufzeit Messungen (im --release Mode)](#laufzeit-messungen-im---release-mode)
+
+## 'Proof-of-Work' als Bibliothek
+
+Transformieren Sie Ihr Binary Projekt in ein Library Projekt, wobei zusätzlich
+ein CLI Programm bereit gestellt wird. Dieses hat seinen Ursprung in `main.rs`.
+Nach der Transformation soll **cargo run** die Funktionalität Ihres hw7/task1
+Programms aufzeigen, und **cargo test** durchläuft die Unit Tests der Library.
+Erstellen Sie auf Basis der bisherigen "unit_test" Datei eine `tests/task1.rs`
+Datei, die die pub Funktionen der Library testet.
+
+### Idiomatischer Code
+
+In dieser Aufgabe sollte Sie besonderen Wert auf Idiomatischen Rust Code legen.
+Auch sollte Ihre `main.rs` Funktion möglichst übersichtlich bleiben. Lagern Sie
+somit Funktionen in Module Ihrer Library oder für Ihr Binary aus. In den
+vorherigen Homeworks haben Sie dazu alle nötigen Kniffe kennen gelernt, die Sie
+nun in Ihrer Lösung verwenden.
+
+### `ANSWERS.md`
+
+In den Aufgaben werden immer wieder Fragen gestellt. Geben Sie die Antworten
+dazu in der Datei `ANSWERS.md`. Eine kurze aber nachvollziehbare Erklärung (eigene
+Worte, kein Code) ist ausreichend. Aufbau und Struktur Ihrer `ANSWERS.md` ist
+Ihnen überlassen. Überzeugen Sie uns Tutoren mit einer klaren und verständlichen
+Struktur (und korrekter Formatierung). 
+
+Kommentieren Sie Ihren Code. Beschreiben Sie in eigenen Worten (kein Copy/Paste
+von Code oder Code Kommentaren) in `ANSWERS.md`, welche Arten der
+Synchronisation und Kommunikation (ausser MPSC) Sie einsetzen und wie Sie die
+maximale Performance erreichen. Wichtig: Kommentare gehören in den Code,
+Erklärungen in die `ANSWERS.md`.
+
+Ihre Erklärung muss nachvollziehbar sein, ohne weitere eigenen Recherchen. Zum
+Beispiel die Antwort: "In der Implementierung wird die Systemfunktion
+_dummy_bla_blub()_ benutzt" ist NICHT ausreichend. Ausreichend wäre: "In der
+Implementierung wird die Systemfunktion _dummy_bla_blub()_ benutzt, die die
+Uhrzeit seit Einschalten des Rechners als UTF String liefert."
+
+Messungen müssen auf Ihrem Container durchgeführt werden.
+
+Und noch einmal: Achten Sie auf eine korrekte Formatierung in Markdown!
+
+## Implementierung
+
+### Parameter _threads_
+
+Erweitern Sie das CLI Programm mit einem weiteren **OPTIONALEN** Parameter:
+`threads`. Wird der Parameter nicht angegeben, analysiert das CLI Programm das
+System und ermittelt die Anzahl der vorhandenen CPUs für 'threads'. Geben Sie
+den Parameter an, können Sie diesen Wert somit 'überschreiben'.
+
+Benutzen Sie dafür die externe [Crate sys-info](<>). Was ist der Unterschied
+zwischen einer logischen und einer physikalischen CPU?
+
+```text
+Proof of Work Mechanism 0.2
+Satoshi Nakamoto
+now the basics in Rust, no C anymore
+
+USAGE:
+    task1 [FLAGS] <base> <difficulty> [threads] [SUBCOMMAND]
+
+FLAGS:
+    -h, --help       Prints help information
+    -V, --version    Prints version information
+
+ARGS:
+    <base>          Sets the base to use
+    <difficulty>    Sets the difficulty to use
+    <threads>       Sets the number of threads to use (default = number of cpus)
+
+SUBCOMMANDS:
+    help       Prints this message or the help of the given subcommand(s)
+    timings    controls timing features
+```
+
+### Flag _verbose_
+
+Mit dem Parameter _-v_, _-vv_ oder _-vvv_ usw. lassen sich unterschiedliche
+viele Zusatzinformationen ausgeben. 
+
+Ohne die Angabe von verbose reduzieren Sie bitte die Ausgaben auf:
+
+    Please wait ...
+    Number: 567621 --> hash: b6bea2a40ed1bd6d9999b2232072092f3df0e02c4b507aa3ad947367b9712345
+
+Wird das Flag -v angegeben, so soll ein Header mit Informationen zum System und
+die Anzahl der Threads, die zur Suche benutzt werden, ausgegeben werden:
+
+```text
+--------------------------------------------
+Container:    : "ct-bsys-ws17-0"
+Physical CPUs : 4
+Logical CPUs  : 4
+CPU Speed     : 1700
+Load Average  : LoadAvg { one: 2.4, five: 2.43, fifteen: 2.46 }
+Processes     : 2690
+--------------------------------------------
+Searching with 2 threads!
+Please wait ...
+Number: 567621 --> hash: b6bea2a40ed1bd6d9999b2232072092f3df0e02c4b507aa3ad947367b9712345
+```
+
+Benutzen Sie für die Systeminformationen die externe [Crate sys-info](<>).
+
+### Suchen mit mehreren Threads
+
+Lagern Sie Ihre bisherige Suche in eine eigene Funktion aus. Schreiben Sie dann
+eine neue Funktion, die das Suchen auf mehrere Threads aufteilt, wenn die Anzahl
+der Threads >1 ist. 
+
+Für die Aufteilung der Aufgabe bietet sich eine "Multiple Producer -> Single
+Consumer" Lösung an. Viele Producer suchen nach dem Hash. Die zu untersuchende
+'Menge' an Zahlen muss dazu geeignet auf alle Threads verteilt werden. Der
+Producer, der ihn findet, sendet den Hash an den Consumer.  
+
+Die Rust Standardbibliothek bietet dafür die [MPSC](<>) Synchronisationsprimitive
+an. Einen ähnlichen Mechanismus haben Sie bereits mit der Pipe kennen gelernt. 
+
+Findet einer der Producer das Ergebnis, so sender er dies dan den Consumer. Der
+Consumer hat dann die ruhmreiche Aufgabe, den Hash ausgeben zu dürfen und
+beendet dann das Programm. 
+
+#### -s Flag
+
+Wird das Flag -s angegeben, so beenden die Producer-Threads die Suche, wenn ein
+Ergebnis gefunden wurde. Synchronisieren Sie dazu alle Producer Threads über
+eine geeignete Variable (kein Mutex, CV oder Semaphore). Die Producer-Threads
+beenden sich somit wenn:
+
+-   ein Ergebnis gefunden wurde
+-   ein anderer Thread ein Ergebnis gefunden hat
+
+Benutzen Sie die Synchronisation geeignet, um den Overhead durch die
+Synchronisation gering zu halten. Ergänzen Sie Ihr Programm z.B. mit einer
+weiteren eigenen 'Option' (Name frei wählbar), um Parameter an Ihrer
+Synchronisation verändern zu können.
+
+#### -w Flag
+
+Wird dieses Flag angegeben, so wartet der Consumer Thread auf das Ende aller
+Producer Threads. Das Flag macht natürlich nur Sinn, wenn das -s Flag angegeben
+ist. Die Trennung von '-s' und '-w' dient in dieser Aufgabe zum
+'Experimentieren'. 
+
+#### Weitere Options
+
+Sofern Sie weitere Optionen beim Aufruf Ihres Programms benötigen, ergänzen Sie
+diese bitte mit einer knappen aber aussagekräftigen Hilfe beim Aufruf mit
+`--help`. Nutzen Sie die `verbose` Ausgaben ('-vv' und '-vvv'), um den Ablauf
+des Programms (und der Threads) zu 'loggen'. Das macht es für uns Tutoren als
+auch für Sie einfacher, den Ablauf Ihres Programms zu 'debuggen'.
+
+#### -help Ausgabe
+
+Mit den obigen Flags und Options sollten Sie nun folgende --help Ausgabe
+erhalten:
+
+```text
+USAGE:
+    task1 [FLAGS] [OPTIONS] <base> <difficulty> [threads] [SUBCOMMAND]
+
+FLAGS:
+    -h, --help       Prints help information
+    -s, --sync       enables sync when solution found
+    -v               Sets the level of verbosity
+    -V, --version    Prints version information
+    -w, --wait       consumer waits for all producers
+
+OPTIONS:
+        --special <VALUE>    sets special sync parameter (Default 0)
+
+ARGS:
+    <base>          Sets the base to use
+    <difficulty>    Sets the difficulty to use
+    <threads>       Sets the number of threads to use (default = number of cpus)
+
+SUBCOMMANDS:
+    help       Prints this message or the help of the given subcommand(s)
+    timings    controls timing features
+```
+
+### Command timings
+
+Bei Angabe des Kommandos 'timings' wird die Gesamtzeit der Suche wie bisher
+ausgegeben. Es genügt somit, bei der Standardausgabe (ohne -v) die Zeit der
+Suche im Consumer Thread zu messen.
+
+```text
+...
+Please wait ...
+Number: 567621 --> hash: b6bea2a40ed1bd6d9999b2232072092f3df0e02c4b507aa3ad947367b9712345
+(Duration: 2s / 2684ms / 2684903us)
+```
+
+Wird das Flag '-v' mit angegeben, so summiert der Consumer Thread die einzelnen
+Suchzeiten der Producer Threads, sowie die insgesamt durchgeführten Loops zur
+Suche. Überlegen Sie sich dazu, wie Sie die nötigen Informationen im Consumer
+von den Producern erfahren. Eine Ausgabe der Ergebnis könnte folgendermassen
+aussehen:
+
+```text
+...
+Sum Loops in Producers:       567600
+Sum Duration in Producers:    10s / 10684ms / 10684637us
+```
+
+Diskutieren Sie die sich ergebenden Werte in `ANSWERS.md`
+
+### Tests
+
+Alle Integrations-Tests der Library liegen unter `tests/`.
+
+TODO: Bei den bats Tests ist ein "timeout"-Test dabei. Dieser schlägt zu, wenn
+Sie kein korrektes Muster als Parameter angeben. Der Test benutzt das Programm
+'timeout', welches auf Linux Systemen installiert ist.
+
+### Laufzeit Messungen (im --release Mode)
+
+(Diskussion Ihrer Ergebnisse in `ANSWERS.md`)
+
+Zeigen Sie Quantitativ den Performance-Gewinn gegenüber der Single-Threaded
+Suche anhand einzelner Ergebnisse. Welche (ungefähre) Abhängigkeit der Laufzeit
+von der Anzahl der Threads können Sie im --release Mode bestimmen? 
+
+Nutzen Sie das Unix Tool **time**, um zusätzliche Ausgaben über die Laufzeit
+Ihres Programms zu erhalten (Antworten in die Datei `ANSWERS.md`). Von Interesse
+sind nur Ihre --release Zeiten:
+
+-   Wie ist die Ausgabe von **time** zu interpretieren, wenn mehrere Threads
+    laufen?
+-   Welche unterschiedlichen Ergebnisse erhalten Sie bei der Option timings? Wie
+    stehen diese im Zusammenhang mit den Ergebnissen von **time**.
+-   Welche Quantitative Auswirkungen hat die Synchronisierung (Warum)? 
+-   Wie verhält sich die Performance, wenn die von Ihnen zusätzlichen Parameter
+    (falls vorhanden) zur Optimierung der Performance variiert werden?
+
+[Crate clap]: https://docs.rs/clap/
+[Crate sha2]: https://docs.rs/sha2/
+[Crate time]: https://docs.rs/time/
+[Crate sys-info]: https://docs.rs/sys-info/
+[MPSC]: https://doc.rust-lang.org/std/sync/mpsc/