Add validation caching interface.

src/trusted/validator/validation_cache.h

+/*
+ * 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.
+ *
+ * CreateQuery: create an opaque query object, given an opaque context object.

[Mark Seaborn, 2012/03/01 00:26:20]

If you could do examples, that would aid readability, e.g.

query = cache->CreateQuery(cache->context);
-- Returns a fresh query object.

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+ * The context object contains persistant variables that will be used for all

[Mark Seaborn, 2012/03/01 00:26:20]

'persistent'

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+ * queries, whereas the query object contains information relevant to a single
+ * validation result.
+ *
+ * AddData: add a blob of binary data to the query.  Conceptually, the query

[Mark Seaborn, 2012/03/01 00:26:20]

query->AddData(query, data, data_size);
-- Adds a blob...

+ * will concatinate all the binary data it is given, in the order it is given,

[Mark Seaborn, 2012/03/01 00:26:20]

'concatenate'

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+ * 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.
+ *
+ * DoQuery: the key is complete, query the validation status.  AddData must

[Mark Seaborn, 2012/03/01 00:26:20]

validation_passed = query->DoQuery(query)

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+ * not be called after calling this function.
+ *
+ * set_status: set the database entry for the given key.  DoQuery must be

[Mark Seaborn, 2012/03/01 00:26:20]

set_status doesn't match.

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+ * called first.
+ *
+ * DestroyQuery: cleanup and deallocate the query object.
+ */
+
+typedef struct NaClValidationCache {
+  void *context;

[Mark Seaborn, 2012/03/01 00:26:20]

Maybe 'handle'

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+  void *(*CreateQuery)(void *context);
+  void (*AddData)(void *query, const unsigned char *data, size_t length);

[Mark Seaborn, 2012/03/01 00:26:20]

uint8_t instead of unsigned char?

[Nick Bray (chromium), 2012/03/01 01:25:16]

Avoids dependencies.

+  int (*DoQuery)(void *query);

[Mark Seaborn, 2012/03/01 00:26:20]

Maybe: GetValidationStatus(), QueryValidationStatus(), QueryCodeValidating()

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+  void (*SetValidates)(void *query);

[Mark Seaborn, 2012/03/01 00:26:20]

Maybe: SetValidationStatus(), MarkCodeValidating(), SetValidationStatusToTrue()

[Nick Bray (chromium), 2012/03/01 01:25:16]

Done.

+  void (*DestroyQuery)(void *query);
+} NaClValidationCache;
+
+EXTERN_C_END
+
+#endif /* NATIVE_CLIENT_SRC_TRUSTED_VALIDATOR_VALIDATION_CACHE_H_ */