From 4f634d205ba36abb1a9b0a0d81a2912f1b3ff96a Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Sat, 3 Aug 2019 16:06:14 +0100
Subject: [PATCH] lib/keyword.3, doc/concepts.tex: Mention performance of
 keyword arguments.

It's surprisingly not that bad.
---
 doc/concepts.tex |  7 +++++++
 lib/keyword.3    | 11 +++++++++++
 2 files changed, 18 insertions(+)

diff --git a/doc/concepts.tex b/doc/concepts.tex
index 39dfd2e..6b21109 100644
--- a/doc/concepts.tex
+++ b/doc/concepts.tex
@@ -534,6 +534,13 @@ Keyword arguments can be provided in three ways.
   call, which is useful when writing wrapper functions.
 \end{enumerate}
 
+Perhaps surprisingly, keyword arguments have a relatively small performance
+impact.  On the author's aging laptop, a call to a simple function, passing
+two out of three keyword arguments, takes about 30 cycles longer than calling
+a standard function which just takes integer arguments.  On the other hand,
+quite a lot of code is involved in decoding keyword arguments, so code size
+will naturally suffer.
+
 Keyword arguments are provided as a general feature for C functions.
 However, Sod has special support for messages which accept keyword arguments
 (\xref{sec:concepts.methods.keywords}); and they play an essential rôle in
diff --git a/lib/keyword.3 b/lib/keyword.3
index 0c6e3e6..db5b86d 100644
--- a/lib/keyword.3
+++ b/lib/keyword.3
@@ -212,6 +212,17 @@ Argument vectors are rather inconvenient to use,
 but are the only practical way in which a caller can decide at runtime
 which arguments to include in a call,
 which is useful when writing wrapper functions.
+.PP
+Perhaps surprisingly,
+keyword arguments have a relatively small performance impact.
+On the author's aging laptop,
+a call to a simple function,
+passing two out of three keyword arguments,
+takes about 30 cycles longer than
+calling a standard function which just takes integer arguments.
+On the other hand,
+quite a lot of code is involved in decoding keyword arguments,
+so code size will naturally suffer.
 .
 .SS Type definitions
 The header file defines two simple structure types.
-- 
2.11.0