cannam@62: // Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors cannam@62: // Licensed under the MIT License: cannam@62: // cannam@62: // Permission is hereby granted, free of charge, to any person obtaining a copy cannam@62: // of this software and associated documentation files (the "Software"), to deal cannam@62: // in the Software without restriction, including without limitation the rights cannam@62: // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell cannam@62: // copies of the Software, and to permit persons to whom the Software is cannam@62: // furnished to do so, subject to the following conditions: cannam@62: // cannam@62: // The above copyright notice and this permission notice shall be included in cannam@62: // all copies or substantial portions of the Software. cannam@62: // cannam@62: // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR cannam@62: // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, cannam@62: // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE cannam@62: // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER cannam@62: // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, cannam@62: // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN cannam@62: // THE SOFTWARE. cannam@62: cannam@62: #ifndef CAPNP_SCHEMA_LOADER_H_ cannam@62: #define CAPNP_SCHEMA_LOADER_H_ cannam@62: cannam@62: #if defined(__GNUC__) && !defined(CAPNP_HEADER_WARNINGS) cannam@62: #pragma GCC system_header cannam@62: #endif cannam@62: cannam@62: #include "schema.h" cannam@62: #include cannam@62: #include cannam@62: cannam@62: namespace capnp { cannam@62: cannam@62: class SchemaLoader { cannam@62: // Class which can be used to construct Schema objects from schema::Nodes as defined in cannam@62: // schema.capnp. cannam@62: // cannam@62: // It is a bad idea to use this class on untrusted input with exceptions disabled -- you may cannam@62: // be exposing yourself to denial-of-service attacks, as attackers can easily construct schemas cannam@62: // that are subtly inconsistent in a way that causes exceptions to be thrown either by cannam@62: // SchemaLoader or by the dynamic API when the schemas are subsequently used. If you enable and cannam@62: // properly catch exceptions, you should be OK -- assuming no bugs in the Cap'n Proto cannam@62: // implementation, of course. cannam@62: cannam@62: public: cannam@62: class LazyLoadCallback { cannam@62: public: cannam@62: virtual void load(const SchemaLoader& loader, uint64_t id) const = 0; cannam@62: // Request that the schema node with the given ID be loaded into the given SchemaLoader. If cannam@62: // the callback is able to find a schema for this ID, it should invoke `loadOnce()` on cannam@62: // `loader` to load it. If no such node exists, it should simply do nothing and return. cannam@62: // cannam@62: // The callback is allowed to load schema nodes other than the one requested, e.g. because it cannam@62: // expects they will be needed soon. cannam@62: // cannam@62: // If the `SchemaLoader` is used from multiple threads, the callback must be thread-safe. cannam@62: // In particular, it's possible for multiple threads to invoke `load()` with the same ID. cannam@62: // If the callback performs a large amount of work to look up IDs, it should be sure to cannam@62: // de-dup these requests. cannam@62: }; cannam@62: cannam@62: SchemaLoader(); cannam@62: cannam@62: SchemaLoader(const LazyLoadCallback& callback); cannam@62: // Construct a SchemaLoader which will invoke the given callback when a schema node is requested cannam@62: // that isn't already loaded. cannam@62: cannam@62: ~SchemaLoader() noexcept(false); cannam@62: KJ_DISALLOW_COPY(SchemaLoader); cannam@62: cannam@62: Schema get(uint64_t id, schema::Brand::Reader brand = schema::Brand::Reader(), cannam@62: Schema scope = Schema()) const; cannam@62: // Gets the schema for the given ID, throwing an exception if it isn't present. cannam@62: // cannam@62: // The returned schema may be invalidated if load() is called with a new schema for the same ID. cannam@62: // In general, you should not call load() while a schema from this loader is in-use. cannam@62: // cannam@62: // `brand` and `scope` are used to determine brand bindings where relevant. `brand` gives cannam@62: // parameter bindings for the target type's brand parameters that were specified at the reference cannam@62: // site. `scope` specifies the scope in which the type ID appeared -- if `brand` itself contains cannam@62: // parameter references or indicates that some parameters will be inherited, these will be cannam@62: // interpreted within / inherited from `scope`. cannam@62: cannam@62: kj::Maybe tryGet(uint64_t id, schema::Brand::Reader bindings = schema::Brand::Reader(), cannam@62: Schema scope = Schema()) const; cannam@62: // Like get() but doesn't throw. cannam@62: cannam@62: Schema getUnbound(uint64_t id) const; cannam@62: // Gets a special version of the schema in which all brand parameters are "unbound". This means cannam@62: // that if you look up a type via the Schema API, and it resolves to a brand parameter, the cannam@62: // returned Type's getBrandParameter() method will return info about that parameter. Otherwise, cannam@62: // normally, all brand parameters that aren't otherwise bound are assumed to simply be cannam@62: // "AnyPointer". cannam@62: cannam@62: Type getType(schema::Type::Reader type, Schema scope = Schema()) const; cannam@62: // Convenience method which interprets a schema::Type to produce a Type object. Implemented in cannam@62: // terms of get(). cannam@62: cannam@62: Schema load(const schema::Node::Reader& reader); cannam@62: // Loads the given schema node. Validates the node and throws an exception if invalid. This cannam@62: // makes a copy of the schema, so the object passed in can be destroyed after this returns. cannam@62: // cannam@62: // If the node has any dependencies which are not already loaded, they will be initialized as cannam@62: // stubs -- empty schemas of whichever kind is expected. cannam@62: // cannam@62: // If another schema for the given reader has already been seen, the loader will inspect both cannam@62: // schemas to determine which one is newer, and use that that one. If the two versions are cannam@62: // found to be incompatible, an exception is thrown. If the two versions differ but are cannam@62: // compatible and the loader cannot determine which is newer (e.g., the only changes are renames), cannam@62: // the existing schema will be preferred. Note that in any case, the loader will end up keeping cannam@62: // around copies of both schemas, so you shouldn't repeatedly reload schemas into the same loader. cannam@62: // cannam@62: // The following properties of the schema node are validated: cannam@62: // - Struct size and preferred list encoding are valid and consistent. cannam@62: // - Struct members are fields or unions. cannam@62: // - Union members are fields. cannam@62: // - Field offsets are in-bounds. cannam@62: // - Ordinals and codeOrders are sequential starting from zero. cannam@62: // - Values are of the right union case to match their types. cannam@62: // cannam@62: // You should assume anything not listed above is NOT validated. In particular, things that are cannam@62: // not validated now, but could be in the future, include but are not limited to: cannam@62: // - Names. cannam@62: // - Annotation values. (This is hard because the annotation declaration is not always cannam@62: // available.) cannam@62: // - Content of default/constant values of pointer type. (Validating these would require knowing cannam@62: // their schema, but even if the schemas are available at validation time, they could be cannam@62: // updated by a subsequent load(), invalidating existing values. Instead, these values are cannam@62: // validated at the time they are used, as usual for Cap'n Proto objects.) cannam@62: // cannam@62: // Also note that unknown types are not considered invalid. Instead, the dynamic API returns cannam@62: // a DynamicValue with type UNKNOWN for these. cannam@62: cannam@62: Schema loadOnce(const schema::Node::Reader& reader) const; cannam@62: // Like `load()` but does nothing if a schema with the same ID is already loaded. In contrast, cannam@62: // `load()` would attempt to compare the schemas and take the newer one. `loadOnce()` is safe cannam@62: // to call even while concurrently using schemas from this loader. It should be considered an cannam@62: // error to call `loadOnce()` with two non-identical schemas that share the same ID, although cannam@62: // this error may or may not actually be detected by the implementation. cannam@62: cannam@62: template cannam@62: void loadCompiledTypeAndDependencies(); cannam@62: // Load the schema for the given compiled-in type and all of its dependencies. cannam@62: // cannam@62: // If you want to be able to cast a DynamicValue built from this SchemaLoader to the compiled-in cannam@62: // type using as(), you must call this method before constructing the DynamicValue. Otherwise, cannam@62: // as() will throw an exception complaining about type mismatch. cannam@62: cannam@62: kj::Array getAllLoaded() const; cannam@62: // Get a complete list of all loaded schema nodes. It is particularly useful to call this after cannam@62: // loadCompiledTypeAndDependencies() in order to get a flat list of all of T's transitive cannam@62: // dependencies. cannam@62: cannam@62: private: cannam@62: class Validator; cannam@62: class CompatibilityChecker; cannam@62: class Impl; cannam@62: class InitializerImpl; cannam@62: class BrandedInitializerImpl; cannam@62: kj::MutexGuarded> impl; cannam@62: cannam@62: void loadNative(const _::RawSchema* nativeSchema); cannam@62: }; cannam@62: cannam@62: template cannam@62: inline void SchemaLoader::loadCompiledTypeAndDependencies() { cannam@62: loadNative(&_::rawSchema()); cannam@62: } cannam@62: cannam@62: } // namespace capnp cannam@62: cannam@62: #endif // CAPNP_SCHEMA_LOADER_H_