cachedb: an optional allocation-free read

get() must hand back a value the caller owns and pkg_free()s, so every
lookup on a hot path costs a pkg_malloc and a pkg_free that exist only to
satisfy that contract. Profiling the cachedb_perf read path put the
allocator at a fixed ~70 ns/op - 15% of a 470 ns lookup over 50 000
entries, 30% of a 236 ns one when the working set is cache resident -
while memcpy never appeared at all.

Add an optional endpoint that reads into a buffer the caller already
owns: no allocation, and one copy instead of two. It is advertised by
CACHEDB_CAP_GET_BUF, so a caller uses it only where a backend offers it
and keeps get() as the fallback; nothing about the existing endpoint
changes, and no backend is obliged to implement the new one.

The contract is written for the failure cases, because those are what a
caller gets wrong: the buffer must be private to the calling process, it
may be written speculatively and abandoned so its contents are undefined
on any non-hit, *vlen and *needed are zeroed before anything else so an
ignored return code yields a zero length rather than an uninitialised
one, and a value that does not fit reports the size it would need in
*needed while leaving *vlen at 0 - {buf, *vlen} is always a valid str.
A hit is 0 here, unlike get(), which is called out in the comment.

CACHEDB_CAP_GET_BUF answers a runtime question - whether the backend a
caller happens to be configured against implements the endpoint. It
cannot answer the one a module has to settle first: whether the core it
is being compiled against has the endpoint at all. get_buf is a member of
cachedb_funcs, so referencing it against an older core is a compile error
rather than a failed test, and the capability is an enum constant,
invisible to the preprocessor. So there is a plain define beside it, and
a module can compile against either core and pick the faster path up on
its own. The runtime check is still required and the comment says so - a
core may carry the endpoint while the backend in use does not implement
it.

The first implementation is cachedb_perf, in the following commit.

Author: Lt-Flash

cachedb/cachedb.h

@@ -162,7 +162,36 @@ typedef struct cachedb_funcs_t {
 	 */
 	int (*is_replicated) (cachedb_con *con);
 
+
 	int capability;
+
+	/**
+	 * OPTIONAL, advertised by CACHEDB_CAP_GET_BUF.  Reads a value into a
+	 * caller-owned buffer, so a hot read path need not allocate: it is
+	 * get() without the pkg_malloc the caller would then have to free.
+	 *
+	 * @buf must be memory private to the calling process (its own stack or
+	 * pkg).  A backend may write into it speculatively and then abandon the
+	 * attempt, so on ANY outcome other than a hit its contents are
+	 * undefined - never a stale previous value to fall back on.  The value
+	 * is not NUL-terminated.
+	 *
+	 * Return values:
+	 *  -3: @buf is too small; *vlen is 0 and *needed holds the size that
+	 *      would be required (the caller may then fall back to get())
+	 *  -2: key does not exist, or has expired
+	 *  -1: internal error, or a malformed request (NULL @buf, or @buflen
+	 *      below the backend's documented minimum)
+	 *   0: found; *vlen bytes were written to @buf, always <= @buflen
+	 *
+	 * *vlen and *needed are zeroed before anything else is done, so a
+	 * caller that ignores the return code reads a zero length rather than
+	 * an uninitialised one.  @needed may be NULL.  NOTE this differs from
+	 * get(), which signals a hit with a positive value at the script
+	 * boundary - a hit here is 0.
+	 */
+	int (*get_buf) (cachedb_con *con, str *attr, char *buf,
+		unsigned int buflen, unsigned int *vlen, unsigned int *needed);
 } cachedb_funcs;
 
 typedef struct cachedb_engines {

cachedb/cachedb_cap.h

@@ -51,8 +51,31 @@ typedef enum {
 	CACHEDB_CAP_MAP_REMOVE   = 1<<13,
 	CACHEDB_CAP_MAP =
 		(CACHEDB_CAP_MAP_GET|CACHEDB_CAP_MAP_SET|CACHEDB_CAP_MAP_REMOVE),
+
+	/* backend implements get_buf() - an allocation-free read into a
+	 * caller-owned buffer.  Optional: every backend still provides get() */
+	CACHEDB_CAP_GET_BUF      = 1<<14,
 } cachedb_cap;
 
+/*
+ * Preprocessor-visible companion to CACHEDB_CAP_GET_BUF.  A consumer cannot test
+ * for the endpoint at runtime alone: get_buf is a struct member, so referencing it
+ * fails to compile against a core that predates it, and the capability above is an
+ * enum constant the preprocessor cannot see.  This lets a module compile against
+ * either core and pick the allocation-free path up automatically:
+ *
+ *   #ifdef CACHEDB_HAVE_GET_BUF
+ *       if (cdbf.get_buf && CACHEDB_CAPABILITY(&cdbf, CACHEDB_CAP_GET_BUF))
+ *           ... use it ...
+ *       else
+ *   #endif
+ *           ... use get() ...
+ *
+ * The runtime half stays necessary: a core may provide the endpoint while the
+ * configured backend does not implement it.
+ */
+#define CACHEDB_HAVE_GET_BUF 1
+
 #define CACHEDB_CAPABILITY(cdbf,cpv) (((cdbf)->capability & (cpv)) == (cpv))
 
 static inline int check_cachedb_api(cachedb_engine *cde)