chapter/compute: Restructure compute chapter

- Break arena into smaller sections and put it under sections
- Make tasks self-contained
- Generate support from solution whenever possible

Signed-off-by: Andrei Miga <[email protected]>
Signed-off-by: Alex Apostolescu <[email protected]>

.github/labeler.yml

@@ -5,7 +5,7 @@ topic/data:
   - 'chapters/data/**/*'
 
 topic/compute:
-  - 'content/chapters/compute/**/*'
+  - 'chapters/compute/**/*'
 
 topic/io:
   - 'content/chapters/io/**/*'

chapters/compute/Makefile

@@ -0,0 +1,37 @@
+# The script expect the source .svg files to be named as $TARGET-$i.svg, where $i is the frame number.
+TARGETS = round-robin race-condition race-condition-toctou race-condition-lock
+RVMD = reveal-md
+MDPP = markdown-pp
+FFMPEG = ffmpeg
+
+SLIDES ?= slides.mdpp
+SLIDES_OUT ?= slides.md
+MEDIA_DIR ?= generated-media
+SITE ?= _site
+OPEN ?= xdg-open
+
+.PHONY: all html clean videos
+
+all: videos html
+
+html: $(SITE)
+
+$(SITE): $(SLIDES)
+	$(MDPP) $< -o $(SLIDES_OUT)
+	$(RVMD) $(SLIDES_OUT) --static $@
+
+videos:
+	mkdir -p $(MEDIA_DIR)
+	for TARGET in $(TARGETS); do \
+		TARGET_DIR=$$(find -name $$TARGET -type d | grep media); \
+		$(FFMPEG) -framerate 0.5 -f image2 -y \
+			-i "$$TARGET_DIR/$$TARGET-%d.svg" -vf format=yuv420p $(MEDIA_DIR)/$$TARGET-generated.gif; \
+	done
+
+open: $(SITE)
+	$(OPEN) $</index.html
+
+clean:
+	-rm -f $(MEDIA_DIR)/*-generated.gif
+	-rm -f *~
+	-rm -fr $(SITE) $(SLIDES_OUT)

chapters/compute/copy-on-write/drills/tasks/page-faults/README.md

@@ -0,0 +1,54 @@
+# Minor and Major Page Faults
+
+The code in `page-faults/support/page_faults.c` generates some minor and major page faults.
+Open 2 terminals: one in which you will run the program, and one which will monitor the page faults of the program.
+In the monitoring terminal, run the following command:
+
+```console
+watch -n 1 'ps -eo min_flt,maj_flt,cmd | grep ./page_faults | head -n 1'
+```
+
+Compile the program and run it in the other terminal.
+You must press `enter` one time, before the program will prompt you to press `enter` more times.
+Watch the first number on the monitoring terminal;
+it increases.
+Those are the minor page faults.
+
+## Minor Page Faults
+
+A minor page fault is generated whenever a requested page is present in the physical memory, as a frame, but that frame isn't allocated to the process generating the request.
+These types of page faults are the most common, and they happen when calling functions from dynamic libraries, allocating heap memory, loading programs, reading files that have been cached, and many more situations.
+Now back to the program.
+
+The monitoring command already starts with some minor page faults, generated when loading the program.
+
+After pressing `enter`, the number increases, because a function from a dynamic library (libc) is fetched when the first `printf()` is executed.
+Subsequent calls to functions that are in the same memory page as `printf()` won't generate other page faults.
+
+After allocating the 100 Bytes, you might not see the number of page faults increase.
+This is because the "bookkeeping" data allocated by `malloc()` was able to fit in an already mapped page.
+The second allocation, the 1GB one, will always gnereate one minor page fault - for the bookkeeping data about the allocated memory zone.
+Notice that not all the pages for the 1GB are allocated.
+They are allocated - and generate page faults - when modified.
+By now you should know that this mechanism is called [copy-on-write](../../copy-on-write/reading/copy-on-write.md).
+
+Continue with pressing `enter` and observing the effects util you reach opening `file.txt`.
+
+Note that neither opening a file, getting information about it, nor mapping it in memory using `mmap()`, generate page faults.
+Also note the `posix_fadvise()` call after the one to `fstat()`.
+With this call we force the OS to not cache the file, so we can generate a **major page fault**.
+
+## Major Page Faults
+
+Major page faults happen when a page is requested, but it isn't present in the physical memory.
+These types of page faults happen in 2 situations:
+
+- a page that was swapped out (to the disk), due to lack of memory, is now accessed - this case is harder to show
+- the OS needs to read a file from the disk, because the file contents aren't present in the cache - the case we are showing now
+
+Press `enter` to print the file contents.
+Note the second number go up in the monitoring terminal.
+
+Comment the `posix_fadvise()` call, recompile the program, and run it again.
+You won't get any major page fault, because the file contents are cached by the OS, to avoid those page faults.
+As a rule, the OS will avoid major page faults whenever possible, because they are very costly in terms of running time.

chapters/compute/copy-on-write/drills/tasks/page-faults/support/Makefile

@@ -0,0 +1,40 @@
+BINARIES = page_faults file.txt
+
+all: $(BINARIES)
+
+CC = gcc
+
+# Get the relative path to the directory of the current makefile.
+MAKEFILE_DIR := $(dir $(lastword $(MAKEFILE_LIST)))
+INCLUDES_DIR := $(MAKEFILE_DIR)..
+UTILS_DIR := $(MAKEFILE_DIR)/utils
+LOGGER_DIR := $(UTILS_DIR)/log
+
+CPPFLAGS += -I$(INCLUDES_DIR)
+CFLAGS += -g -Wall -Wextra
+LDFLAGS += -z lazy
+LOGGER_OBJ = log.o
+LOGGER = $(LOGGER_DIR)/$(LOGGER_OBJ)
+
+SRCS = $(wildcard *.c)
+OBJS = $(SRCS:.c=.o)
+
+$(LOGGER_OBJ): $(LOGGER_DIR)/log.c
+	@make -C $(LOGGER_DIR) $(LOGGER_OBJ)
+
+$(OBJS): %.o: %.c
+
+clean::
+	-rm -f $(OBJS) $(LOGGER)
+
+.PHONY: clean
+
+$(BINARIES): $(LOGGER)
+
+clean::
+	-rm -f $(BINARIES)
+
+.PHONY: all clean
+
+file.txt:
+	curl metaphorpsum.com/paragraphs/20/50 > $@

content/chapters/compute/lab/support/page-faults/page_faults.c → chapters/compute/copy-on-write/drills/tasks/page-faults/support/page_faults.c

@@ -19,8 +19,6 @@ int main(void)
 	struct stat filestat;
 	char *data;
 
-	getchar();
-
 	printf("Press enter to allocate 100 Bytes\n");
 	getchar();
 

chapters/compute/copy-on-write/drills/tasks/page-faults/support/utils/log/log.c

@@ -0,0 +1,170 @@
+/*
+ * Copyright (c) 2020 rxi
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to
+ * deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+ * sell copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+ * IN THE SOFTWARE.
+ */
+
+/* Github link: https://github.com/rxi/log.c */
+
+#include "log.h"
+
+#define MAX_CALLBACKS 32
+
+typedef struct {
+  log_LogFn fn;
+  void *udata;
+  int level;
+} Callback;
+
+static struct {
+  void *udata;
+  log_LockFn lock;
+  int level;
+  bool quiet;
+  Callback callbacks[MAX_CALLBACKS];
+} L;
+
+
+static const char *level_strings[] = {
+  "TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"
+};
+
+#ifdef LOG_USE_COLOR
+static const char *level_colors[] = {
+  "\x1b[94m", "\x1b[36m", "\x1b[32m", "\x1b[33m", "\x1b[31m", "\x1b[35m"
+};
+#endif
+
+
+static void stdout_callback(log_Event *ev) {
+  char buf[16];
+  buf[strftime(buf, sizeof(buf), "%H:%M:%S", ev->time)] = '\0';
+#ifdef LOG_USE_COLOR
+  fprintf(
+    ev->udata, "%s %s%-5s\x1b[0m \x1b[90m%s:%d:\x1b[0m ",
+    buf, level_colors[ev->level], level_strings[ev->level],
+    ev->file, ev->line);
+#else
+  fprintf(
+    ev->udata, "%s %-5s %s:%d: ",
+    buf, level_strings[ev->level], ev->file, ev->line);
+#endif
+  vfprintf(ev->udata, ev->fmt, ev->ap);
+  fprintf(ev->udata, "\n");
+  fflush(ev->udata);
+}
+
+
+static void file_callback(log_Event *ev) {
+  char buf[64];
+  buf[strftime(buf, sizeof(buf), "%Y-%m-%d %H:%M:%S", ev->time)] = '\0';
+  fprintf(
+    ev->udata, "%s %-5s %s:%d: ",
+    buf, level_strings[ev->level], ev->file, ev->line);
+  vfprintf(ev->udata, ev->fmt, ev->ap);
+  fprintf(ev->udata, "\n");
+  fflush(ev->udata);
+}
+
+
+static void lock(void)   {
+  if (L.lock) { L.lock(true, L.udata); }
+}
+
+
+static void unlock(void) {
+  if (L.lock) { L.lock(false, L.udata); }
+}
+
+
+const char* log_level_string(int level) {
+  return level_strings[level];
+}
+
+
+void log_set_lock(log_LockFn fn, void *udata) {
+  L.lock = fn;
+  L.udata = udata;
+}
+
+
+void log_set_level(int level) {
+  L.level = level;
+}
+
+
+void log_set_quiet(bool enable) {
+  L.quiet = enable;
+}
+
+
+int log_add_callback(log_LogFn fn, void *udata, int level) {
+  for (int i = 0; i < MAX_CALLBACKS; i++) {
+    if (!L.callbacks[i].fn) {
+      L.callbacks[i] = (Callback) { fn, udata, level };
+      return 0;
+    }
+  }
+  return -1;
+}
+
+
+int log_add_fp(FILE *fp, int level) {
+  return log_add_callback(file_callback, fp, level);
+}
+
+
+static void init_event(log_Event *ev, void *udata) {
+  if (!ev->time) {
+    time_t t = time(NULL);
+    ev->time = localtime(&t);
+  }
+  ev->udata = udata;
+}
+
+
+void log_log(int level, const char *file, int line, const char *fmt, ...) {
+  log_Event ev = {
+    .fmt   = fmt,
+    .file  = file,
+    .line  = line,
+    .level = level,
+  };
+
+  lock();
+
+  if (!L.quiet && level >= L.level) {
+    init_event(&ev, stderr);
+    va_start(ev.ap, fmt);
+    stdout_callback(&ev);
+    va_end(ev.ap);
+  }
+
+  for (int i = 0; i < MAX_CALLBACKS && L.callbacks[i].fn; i++) {
+    Callback *cb = &L.callbacks[i];
+    if (level >= cb->level) {
+      init_event(&ev, cb->udata);
+      va_start(ev.ap, fmt);
+      cb->fn(&ev);
+      va_end(ev.ap);
+    }
+  }
+
+  unlock();
+}

chapters/compute/copy-on-write/drills/tasks/page-faults/support/utils/log/log.h

@@ -0,0 +1,59 @@
+/**
+ * Copyright (c) 2020 rxi
+ *
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the MIT license. See `log.c` for details.
+ */
+
+/* Github link: https://github.com/rxi/log.c */
+
+#ifndef LOG_H
+#define LOG_H
+
+#include <stdio.h>
+#include <stdarg.h>
+#include <stdbool.h>
+#include <time.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define LOG_VERSION "0.1.0"
+
+typedef struct {
+  va_list ap;
+  const char *fmt;
+  const char *file;
+  struct tm *time;
+  void *udata;
+  int line;
+  int level;
+} log_Event;
+
+typedef void (*log_LogFn)(log_Event *ev);
+typedef void (*log_LockFn)(bool lock, void *udata);
+
+enum { LOG_TRACE, LOG_DEBUG, LOG_INFO, LOG_WARN, LOG_ERROR, LOG_FATAL };
+
+#define log_trace(...) log_log(LOG_TRACE, __FILE__, __LINE__, __VA_ARGS__)
+#define log_debug(...) log_log(LOG_DEBUG, __FILE__, __LINE__, __VA_ARGS__)
+#define log_info(...)  log_log(LOG_INFO,  __FILE__, __LINE__, __VA_ARGS__)
+#define log_warn(...)  log_log(LOG_WARN,  __FILE__, __LINE__, __VA_ARGS__)
+#define log_error(...) log_log(LOG_ERROR, __FILE__, __LINE__, __VA_ARGS__)
+#define log_fatal(...) log_log(LOG_FATAL, __FILE__, __LINE__, __VA_ARGS__)
+
+const char* log_level_string(int level);
+void log_set_lock(log_LockFn fn, void *udata);
+void log_set_level(int level);
+void log_set_quiet(bool enable);
+int log_add_callback(log_LogFn fn, void *udata, int level);
+int log_add_fp(FILE *fp, int level);
+
+void log_log(int level, const char *file, int line, const char *fmt, ...);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* LOG_H */