add benchmark

* add benchmark
* Update README.md

Author: PeterIvanov

.gitignore

@@ -10,3 +10,7 @@
 
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
+
+# IDE
+.idea/
+*.iml

README.md

@@ -36,7 +36,7 @@ An *errorx* library makes an approach to create a toolset that would help remedy
 
 As a result, the goal of the library is to provide a brief, expressive syntax for a conventional error handling and to discourage usage patterns that bring more harm than they're worth.
 
-Error-related, negative codepath is typically less well tested, though of, and may confuse the reader more than its positive counterpart. Therefore, an error system could do well without too much of a flexibility and unpredictability
+Error-related, negative codepath is typically less well tested, though of, and may confuse the reader more than its positive counterpart. Therefore, an error system could do well without too much of a flexibility and unpredictability.
 
 # errorx
 
@@ -146,6 +146,36 @@ This way, a receiver of an error always treats it the same way, and it is the pr
 
 Other relevant tools include ```EnsureStackTrace(err)``` to provide an error of unknown nature with a stack trace, if it lacks one.
 
+### Stack traces benchmark
+
+As performance is obviously an issue, some measurements are in order. The benchmark is provided with the library. In all of benchmark cases, a very simple code is called that does nothing but grows a number of frames and immediately returns an error.
+
+Result sample, MacBook Pro Intel Core i7-6920HQ CPU @ 2.90GHz 4 core:
+
+name | runs | ns/op | note
+------ | ------: | ------: | ------
+BenchmarkSimpleError10                    | 20000000 |     57.2 | simple error, 10 frames deep
+BenchmarkErrorxError10                    | 10000000 |      138 | same with errorx error
+BenchmarkStackTraceErrorxError10          |  1000000 |     1601 | same with collected stack trace
+BenchmarkSimpleError100                   |  3000000 |      421 | simple error, 100 frames deep
+BenchmarkErrorxError100                   |  3000000 |      507 | same with errorx error
+BenchmarkStackTraceErrorxError100         |   300000 |     4450 | same with collected stack trace
+BenchmarkStackTraceNaiveError100-8         	   | 2000 |	    588135 | same with naive debug.Stack() error implementation
+BenchmarkSimpleErrorPrint100              |  2000000 |      617 | simple error, 100 frames deep, format output
+BenchmarkErrorxErrorPrint100              |  2000000 |      935 | same with errorx error
+BenchmarkStackTraceErrorxErrorPrint100    |    30000 |    58965 | same with collected stack trace
+BenchmarkStackTraceNaiveErrorPrint100-8    	   | 2000 |	    599155 | same with naive debug.Stack() error implementation
+
+Key takeaways:
+ * With deep enough call stack, trace capture brings **10x slowdown**
+ * This is an absolute **worst case measurement, no-op function**; in a real life, much more time is spent doing actual work
+ * Then again, in real life code invocation does not always result in error, so the overhead is proportional to the % of error returns
+ * Still, it pays to omit stack trace collection when it would be of no use
+ * It is actually **much more expensive to format** an error with a stack trace than to create it, roughly **another 10x**
+ * Compared to the most naive approach to stack trace collection, error creation it is **100x** cheaper with errorx
+ * Therefore, it is totally OK to create an error with a stack trace that would then be handled and not printed to log
+ * Realistically, stack trace overhead is only painful either if a code is very hot (called a lot and returns errors often) or if an error is used as a control flow mechanism and does not constitute an actual problem; in both cases, stack trace should be omitted
+
 ## More
 
 See godoc for other *errorx* features:

benchmark/stacktrace_benchmark_test.go

@@ -0,0 +1,203 @@
+package benchmark
+
+import (
+	"errors"
+	"fmt"
+	"runtime/debug"
+	"testing"
+
+	"github.com/joomcode/errorx"
+)
+
+var errorSink error
+
+func BenchmarkSimpleError10(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(10, createSimpleError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkErrorxError10(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(10, createSimpleErrorxError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkStackTraceErrorxError10(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(10, createErrorxError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkSimpleError100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(100, createSimpleError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkErrorxError100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(100, createSimpleErrorxError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkStackTraceErrorxError100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(100, createErrorxError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkStackTraceNaiveError100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		errorSink = function0(100, createNaiveError)
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkSimpleErrorPrint100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		err := function0(100, createSimpleError)
+		emulateErrorPrint(err)
+		errorSink = err
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkErrorxErrorPrint100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		err := function0(100, createSimpleErrorxError)
+		emulateErrorPrint(err)
+		errorSink = err
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkStackTraceErrorxErrorPrint100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		err := function0(100, createErrorxError)
+		emulateErrorPrint(err)
+		errorSink = err
+	}
+	consumeResult(errorSink)
+}
+
+func BenchmarkStackTraceNaiveErrorPrint100(b *testing.B) {
+	for n := 0; n < b.N; n++ {
+		err := function0(100, createNaiveError)
+		emulateErrorPrint(err)
+		errorSink = err
+	}
+	consumeResult(errorSink)
+}
+
+func createSimpleError() error {
+	return errors.New("benchmark")
+}
+
+var (
+	Errors            = errorx.NewNamespace("errorx.benchmark")
+	NoStackTraceError = Errors.NewType("no_stack_trace").ApplyModifiers(errorx.TypeModifierOmitStackTrace)
+	StackTraceError   = Errors.NewType("stack_trace")
+)
+
+func createSimpleErrorxError() error {
+	return NoStackTraceError.New("benchmark")
+}
+
+func createErrorxError() error {
+	return StackTraceError.New("benchmark")
+}
+
+type naiveError struct {
+	stack []byte
+}
+
+func (err naiveError) Error() string {
+	return fmt.Sprintf("benchmark\n%s", err.stack)
+}
+
+func createNaiveError() error {
+	return naiveError{stack: debug.Stack()}
+}
+
+func function0(depth int, generate func() error) error {
+	if depth == 0 {
+		return generate()
+	}
+
+	switch depth % 3 {
+	case 0:
+		return function1(depth-1, generate)
+	case 1:
+		return function2(depth-1, generate)
+	default:
+		return function3(depth-1, generate)
+	}
+}
+
+func function1(depth int, generate func() error) error {
+	if depth == 0 {
+		return generate()
+	}
+
+	return function4(depth-1, generate)
+}
+
+func function2(depth int, generate func() error) error {
+	if depth == 0 {
+		return generate()
+	}
+
+	return function4(depth-1, generate)
+}
+
+func function3(depth int, generate func() error) error {
+	if depth == 0 {
+		return generate()
+	}
+
+	return function4(depth-1, generate)
+}
+
+func function4(depth int, generate func() error) error {
+	switch depth {
+	case 0:
+		return generate()
+	default:
+		return function0(depth-1, generate)
+	}
+}
+
+type sinkError struct {
+	value int
+}
+
+func (sinkError) Error() string {
+	return ""
+}
+
+// Perform error formatting and consume the result to disallow optimizations against output
+func emulateErrorPrint(err error) {
+	output := fmt.Sprintf("%+v", err)
+	if len(output) > 10000 && output[1000:1004] == "DOOM" {
+		panic("this was not supposed to happen")
+	}
+}
+
+// Consume error with a possible side effect to disallow optimizations against err
+func consumeResult(err error) {
+	if e, ok := err.(sinkError); ok && e.value == 1 {
+		panic("this was not supposed to happen")
+	}
+}
+
+// A public function to discourage optimizations against errorSink variable
+func ExportSink() error {
+	return errorSink
+}