Add testpoint mechanism proposal 0005

A patch is coming later on that implements this proposal. Authored by
Christian Babeux <christian.babeux@efficios.com>.

Signed-off-by: David Goulet <dgoulet@efficios.com>

diff --git a/doc/proposals/0005-testpoint-mechanism.txt b/doc/proposals/0005-testpoint-mechanism.txt
new file mode 100644 (file)
index 0000000..5d4c1de
--- /dev/null
+++ b/doc/proposals/0005-testpoint-mechanism.txt
@@ -0,0 +1,107 @@
+RFC - Testpoint mechanism\r
+\r
+Author: Christian Babeux <christian.babeux@efficios.com>\r
+\r
+Contributors:\r
+       * Mathieu Desnoyers <mathieu.desnoyers@efficios.com>\r
+\r
+Version:\r
+       - v0.1: 11/09/2012\r
+               * Initial proposal\r
+\r
+Motivation\r
+----------\r
+\r
+The main goal behind the testpoint mechanism is to be able to test and\r
+validate failure cases in different portion of the LTTng codebase. It\r
+could also be used by developers as a debugging aid.\r
+\r
+By injecting code at runtime in the lttng daemons/processes/executables,\r
+we can painlessly trigger faulty behavior, test errors paths or even\r
+reproduce race conditions by introducing or exacerbating delays between\r
+threads.\r
+\r
+Requirements\r
+------------\r
+\r
+The testpoint mechanism should be able to be triggered via scripts to\r
+automate testing efforts.\r
+\r
+Ideally, the testpoint mechanism should *NOT* incur a significant\r
+performance hit if we want to leave it always on, in a similar fashion\r
+to the assert() macros.\r
+\r
+By leaving it always on, any user is able to use our tests and validate\r
+the behavior of his installation via a simple 'make check' execution.\r
+\r
+Proposed solution\r
+-----------------\r
+\r
+This patch introduce two new macros: TESTPOINT_DECL(name)\r
+and testpoint(name).\r
+\r
+Here a quick example that shows how to use the testpoint mechanism:\r
+\r
+file: main.c\r
+#include <stdio.h>\r
+#include <common/testpoint/testpoint/testpoint.h>\r
+\r
+/* Testpoint declaration */\r
+TESTPOINT_DECL(interesting_function)\r
+\r
+void interesting_function(void)\r
+{\r
+       testpoint(interesting_function);\r
+       /* Some processing that can fail */\r
+       ...\r
+}\r
+\r
+int main(int argc, char *argv[])\r
+{\r
+       interesting_function();\r
+       ...\r
+       printf("End");\r
+}\r
+\r
+file: testpoint.c\r
+#include <stdio.h>\r
+void __testpoint_interesting_function(void)\r
+{\r
+       printf("In testpoint of interesting function!");\r
+}\r
+\r
+Compile:\r
+gcc -o test main.c\r
+gcc -fPIC -shared -o testpoint.so testpoint.c\r
+\r
+Run:\r
+> ./test\r
+  End\r
+> export LTTNG_TESTPOINT_ENABLE=1\r
+> LD_PRELOAD=testpoint.so ./test\r
+  In testpoint of interesting function!\r
+  End\r
+> export LTTNG_TESTPOINT_ENABLE=0\r
+> LD_PRELOAD=testpoint.so ./test\r
+  End\r
+\r
+The testpoint mechanism is triggered via the preloading of a shared\r
+object containing the appropriate testpoint symbols and by setting the\r
+LTTNG_TESTPOINT_ENABLE environment variable.\r
+\r
+The check on this environment variable is done on the application\r
+startup with the help of a constructor (lttng_testpoint_check) which\r
+toggle a global state variable indicating whether or not the testpoints\r
+should be activated.\r
+\r
+When enabled, the testpoint() macro calls an underlying wrapper specific\r
+to the testpoint and simply try to lookup the testpoint symbol via a\r
+dlsym() call.\r
+\r
+When disabled, the testpoint() call will only incur an additionnal test\r
+per testpoint on a global variable. This performance 'hit' should be\r
+acceptable for production use.\r
+\r
+As stated previously, the testpoint mechanism should be *always on*.  It\r
+can be explicitly disabled via CFLAGS="-DNTESTPOINT" in a way similar to\r
+NDEBUG and assert().\r