1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2023 Google LLC. All rights reserved. 3 // 4 // Use of this source code is governed by a BSD-style 5 // license that can be found in the LICENSE file or at 6 // https://developers.google.com/open-source/licenses/bsd 7 8 #ifndef UPB_MINI_TABLE_EXTENSION_REGISTRY_H_ 9 #define UPB_MINI_TABLE_EXTENSION_REGISTRY_H_ 10 11 #include "upb/mem/arena.h" 12 #include "upb/mini_table/extension.h" 13 #include "upb/mini_table/message.h" 14 15 // Must be last. 16 #include "upb/port/def.inc" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /* Extension registry: a dynamic data structure that stores a map of: 23 * (upb_MiniTable, number) -> extension info 24 * 25 * upb_decode() uses upb_ExtensionRegistry to look up extensions while parsing 26 * binary format. 27 * 28 * upb_ExtensionRegistry is part of the mini-table (msglayout) family of 29 * objects. Like all mini-table objects, it is suitable for reflection-less 30 * builds that do not want to expose names into the binary. 31 * 32 * Unlike most mini-table types, upb_ExtensionRegistry requires dynamic memory 33 * allocation and dynamic initialization: 34 * * If reflection is being used, then upb_DefPool will construct an appropriate 35 * upb_ExtensionRegistry automatically. 36 * * For a mini-table only build, the user must manually construct the 37 * upb_ExtensionRegistry and populate it with all of the extensions the user 38 * cares about. 39 * * A third alternative is to manually unpack relevant extensions after the 40 * main parse is complete, similar to how Any works. This is perhaps the 41 * nicest solution from the perspective of reducing dependencies, avoiding 42 * dynamic memory allocation, and avoiding the need to parse uninteresting 43 * extensions. The downsides are: 44 * (1) parse errors are not caught during the main parse 45 * (2) the CPU hit of parsing comes during access, which could cause an 46 * undesirable stutter in application performance. 47 * 48 * Users cannot directly get or put into this map. Users can only add the 49 * extensions from a generated module and pass the extension registry to the 50 * binary decoder. 51 * 52 * A upb_DefPool provides a upb_ExtensionRegistry, so any users who use 53 * reflection do not need to populate a upb_ExtensionRegistry directly. 54 */ 55 56 typedef struct upb_ExtensionRegistry upb_ExtensionRegistry; 57 58 // Creates a upb_ExtensionRegistry in the given arena. 59 // The arena must outlive any use of the extreg. 60 UPB_API upb_ExtensionRegistry* upb_ExtensionRegistry_New(upb_Arena* arena); 61 62 UPB_API bool upb_ExtensionRegistry_Add(upb_ExtensionRegistry* r, 63 const upb_MiniTableExtension* e); 64 65 // Adds the given extension info for the array |e| of size |count| into the 66 // registry. If there are any errors, the entire array is backed out. 67 // The extensions must outlive the registry. 68 // Possible errors include OOM or an extension number that already exists. 69 // TODO: There is currently no way to know the exact reason for failure. 70 bool upb_ExtensionRegistry_AddArray(upb_ExtensionRegistry* r, 71 const upb_MiniTableExtension** e, 72 size_t count); 73 74 #ifdef UPB_LINKARR_DECLARE 75 76 // Adds all extensions linked into the binary into the registry. The set of 77 // linked extensions is assembled by the linker using linker arrays. This 78 // will likely not work properly if the extensions are split across multiple 79 // shared libraries. 80 // 81 // Returns true if all extensions were added successfully, false on out of 82 // memory or if any extensions were already present. 83 // 84 // This API is currently not available on MSVC (though it *is* available on 85 // Windows using clang-cl). 86 UPB_API bool upb_ExtensionRegistry_AddAllLinkedExtensions( 87 upb_ExtensionRegistry* r); 88 89 #endif // UPB_LINKARR_DECLARE 90 91 // Looks up the extension (if any) defined for message type |t| and field 92 // number |num|. Returns the extension if found, otherwise NULL. 93 UPB_API const upb_MiniTableExtension* upb_ExtensionRegistry_Lookup( 94 const upb_ExtensionRegistry* r, const upb_MiniTable* t, uint32_t num); 95 96 #ifdef __cplusplus 97 } /* extern "C" */ 98 #endif 99 100 #include "upb/port/undef.inc" 101 102 #endif /* UPB_MINI_TABLE_EXTENSION_REGISTRY_H_ */ 103