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 // Functions for linking MiniTables together once they are built from a 9 // MiniDescriptor. 10 // 11 // These functions have names like upb_MiniTable_Link() because they operate on 12 // MiniTables. We put them here, rather than in the mini_table/ directory, 13 // because they are only needed when building MiniTables from MiniDescriptors. 14 // The interfaces in mini_table/ assume that MiniTables are immutable. 15 16 #ifndef UPB_MINI_DESCRIPTOR_LINK_H_ 17 #define UPB_MINI_DESCRIPTOR_LINK_H_ 18 19 #include "upb/base/status.h" 20 #include "upb/mem/arena.h" 21 #include "upb/mini_table/enum.h" 22 #include "upb/mini_table/field.h" 23 #include "upb/mini_table/message.h" 24 #include "upb/mini_table/sub.h" 25 26 // Must be last. 27 #include "upb/port/def.inc" 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 // Links a sub-message field to a MiniTable for that sub-message. If a 34 // sub-message field is not linked, it will be treated as an unknown field 35 // during parsing, and setting the field will not be allowed. It is possible 36 // to link the message field later, at which point it will no longer be treated 37 // as unknown. However there is no synchronization for this operation, which 38 // means parallel mutation requires external synchronization. 39 // Returns success/failure. 40 UPB_API bool upb_MiniTable_SetSubMessage(upb_MiniTable* table, 41 upb_MiniTableField* field, 42 const upb_MiniTable* sub); 43 44 // Links an enum field to a MiniTable for that enum. 45 // All enum fields must be linked prior to parsing. 46 // Returns success/failure. 47 UPB_API bool upb_MiniTable_SetSubEnum(upb_MiniTable* table, 48 upb_MiniTableField* field, 49 const upb_MiniTableEnum* sub); 50 51 // Returns a list of fields that require linking at runtime, to connect the 52 // MiniTable to its sub-messages and sub-enums. The list of fields will be 53 // written to the `subs` array, which must have been allocated by the caller 54 // and must be large enough to hold a list of all fields in the message. 55 // 56 // The order of the fields returned by this function is significant: it matches 57 // the order expected by upb_MiniTable_Link() below. 58 // 59 // The return value packs the sub-message count and sub-enum count into a single 60 // integer like so: 61 // return (msg_count << 16) | enum_count; 62 UPB_API uint32_t upb_MiniTable_GetSubList(const upb_MiniTable* mt, 63 const upb_MiniTableField** subs); 64 65 // Links a message to its sub-messages and sub-enums. The caller must pass 66 // arrays of sub-tables and sub-enums, in the same length and order as is 67 // returned by upb_MiniTable_GetSubList() above. However, individual elements 68 // of the sub_tables may be NULL if those sub-messages were tree shaken. 69 // 70 // Returns false if either array is too short, or if any of the tables fails 71 // to link. 72 UPB_API bool upb_MiniTable_Link(upb_MiniTable* mt, 73 const upb_MiniTable** sub_tables, 74 size_t sub_table_count, 75 const upb_MiniTableEnum** sub_enums, 76 size_t sub_enum_count); 77 78 #ifdef __cplusplus 79 } /* extern "C" */ 80 #endif 81 82 #include "upb/port/undef.inc" 83 84 #endif // UPB_MINI_DESCRIPTOR_LINK_H_ 85