Add validation caching interface.

src/trusted/validator/validation_cache.h

+/*

[Mark Seaborn, 2012/02/29 21:33:34]

Create a subdirectory for these files, e.g. 'trusted/validator/cache'

[Nick Bray (chromium), 2012/02/29 22:58:09]

Why?  A directory for two files, and adding a build.scons files seems like extra
clutter.

+ * Copyright (c) 2012 The Native Client Authors. All rights reserved.
+ * Use of this source code is governed by a BSD-style license that can be
+ * found in the LICENSE file.
+ */
+
+#ifndef NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_
+#define NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_
+
+#include "native_client/src/include/nacl_base.h"
+
+EXTERN_C_BEGIN
+
+/*
+ * This interface allows the validator to query a database of validation results
+ * while hiding details of how the database is implemented.
+ *
+ * create_query: create an opaque query object, given an opaque context object.
+ * The context object contains persistant variables that will be used for all
+ * queries, whereas the query object contains information relevant to a single
+ * validation result.
+ *
+ * add_data: add a blob of binary data to the query.  Conceptually, the query
+ * will concatinate all the binary data it is given, in the order it is given,
+ * and use the concatenated blob as a key to look up validation results in a
+ * database.  In practice, all of the data is hashed into a reasonabally sized
+ * key.  The validation cache doesn't care what data it is given, it is the
+ * responsibility of the validator to provide enough information to uniquely
+ * identify the validation result.  This gives flexibility to use different
+ * types of keys for different validators and different sources of code.
+ *
+ * do_query: the key is complete, query the validation status.  add_data must
+ * not be called after calling this function.
+ *
+ * set_status: set the database entry for the given key.  do_query must be
+ * called first.
+ *
+ * destroy_query: cleanup and deallocate the query object.
+ */
+
+typedef struct NaClValidationCache {

[Mark Seaborn, 2012/02/29 21:33:34]

Maybe 'NaClValidationCacheFuncs', because this isn't a cache instance.

[Nick Bray (chromium), 2012/02/29 22:58:09]

I wanted to avoid embedding to many implementation details in the type name. 
This seemed simplest.  We can talk in person.

+  void *(*create_query)(void *context);

[Mark Seaborn, 2012/02/29 21:33:34]

-> CreateQuery.  We use CamelCase for method names in vtables.

[Nick Bray (chromium), 2012/02/29 22:58:09]

Done.

+  void (*add_data)(void *query, const unsigned char *data, size_t length);
+  int (*do_query)(void *query);
+  void (*set_validates)(void *query);
+  void (*destroy_query)(void *query);
+} NaClValidationCache;

[Mark Seaborn, 2012/02/29 21:33:34]

How about adding 'void *context' as a member of the struct?  By passing the two
around as a pair you've effectively got a fat pointer.  You might as well
combine them into a single reference.

[Nick Bray (chromium), 2012/02/29 22:58:09]

Done.

+
+EXTERN_C_END
+
+#endif /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_ */