1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 Google Inc. All rights reserved. 3 // https://developers.google.com/protocol-buffers/ 4 // 5 // Redistribution and use in source and binary forms, with or without 6 // modification, are permitted provided that the following conditions are 7 // met: 8 // 9 // * Redistributions of source code must retain the above copyright 10 // notice, this list of conditions and the following disclaimer. 11 // * Redistributions in binary form must reproduce the above 12 // copyright notice, this list of conditions and the following disclaimer 13 // in the documentation and/or other materials provided with the 14 // distribution. 15 // * Neither the name of Google Inc. nor the names of its 16 // contributors may be used to endorse or promote products derived from 17 // this software without specific prior written permission. 18 // 19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31 #ifndef GOOGLE_PROTOBUF_PYTHON_CPP_DESCRIPTOR_POOL_H__ 32 #define GOOGLE_PROTOBUF_PYTHON_CPP_DESCRIPTOR_POOL_H__ 33 34 #include <Python.h> 35 36 #include <google/protobuf/stubs/hash.h> 37 #include <google/protobuf/descriptor.h> 38 39 namespace google { 40 namespace protobuf { 41 class MessageFactory; 42 43 namespace python { 44 45 // The (meta) type of all Messages classes. 46 struct CMessageClass; 47 48 // Wraps operations to the global DescriptorPool which contains information 49 // about all messages and fields. 50 // 51 // There is normally one pool per process. We make it a Python object only 52 // because it contains many Python references. 53 // TODO(amauryfa): See whether such objects can appear in reference cycles, and 54 // consider adding support for the cyclic GC. 55 // 56 // "Methods" that interacts with this DescriptorPool are in the cdescriptor_pool 57 // namespace. 58 typedef struct PyDescriptorPool { 59 PyObject_HEAD 60 61 // The C++ pool containing Descriptors. 62 DescriptorPool* pool; 63 64 // The C++ pool acting as an underlay. Can be NULL. 65 // This pointer is not owned and must stay alive. 66 const DescriptorPool* underlay; 67 68 // The C++ descriptor database used to fetch unknown protos. Can be NULL. 69 // This pointer is owned. 70 const DescriptorDatabase* database; 71 72 // DynamicMessageFactory used to create C++ instances of messages. 73 // This object cache the descriptors that were used, so the DescriptorPool 74 // needs to get rid of it before it can delete itself. 75 // 76 // Note: A C++ MessageFactory is different from the Python MessageFactory. 77 // The C++ one creates messages, when the Python one creates classes. 78 MessageFactory* message_factory; 79 80 // Make our own mapping to retrieve Python classes from C++ descriptors. 81 // 82 // Descriptor pointers stored here are owned by the DescriptorPool above. 83 // Python references to classes are owned by this PyDescriptorPool. 84 typedef hash_map<const Descriptor*, CMessageClass*> ClassesByMessageMap; 85 ClassesByMessageMap* classes_by_descriptor; 86 87 // Cache the options for any kind of descriptor. 88 // Descriptor pointers are owned by the DescriptorPool above. 89 // Python objects are owned by the map. 90 hash_map<const void*, PyObject*>* descriptor_options; 91 } PyDescriptorPool; 92 93 94 extern PyTypeObject PyDescriptorPool_Type; 95 96 namespace cdescriptor_pool { 97 98 // Looks up a message by name. 99 // Returns a message Descriptor, or NULL if not found. 100 const Descriptor* FindMessageTypeByName(PyDescriptorPool* self, 101 const string& name); 102 103 // Registers a new Python class for the given message descriptor. 104 // On error, returns -1 with a Python exception set. 105 int RegisterMessageClass(PyDescriptorPool* self, 106 const Descriptor* message_descriptor, 107 CMessageClass* message_class); 108 109 // Retrieves the Python class registered with the given message descriptor. 110 // 111 // Returns a *borrowed* reference if found, otherwise returns NULL with an 112 // exception set. 113 CMessageClass* GetMessageClass(PyDescriptorPool* self, 114 const Descriptor* message_descriptor); 115 116 // The functions below are also exposed as methods of the DescriptorPool type. 117 118 // Looks up a message by name. Returns a PyMessageDescriptor corresponding to 119 // the field on success, or NULL on failure. 120 // 121 // Returns a new reference. 122 PyObject* FindMessageByName(PyDescriptorPool* self, PyObject* name); 123 124 // Looks up a field by name. Returns a PyFieldDescriptor corresponding to 125 // the field on success, or NULL on failure. 126 // 127 // Returns a new reference. 128 PyObject* FindFieldByName(PyDescriptorPool* self, PyObject* name); 129 130 // Looks up an extension by name. Returns a PyFieldDescriptor corresponding 131 // to the field on success, or NULL on failure. 132 // 133 // Returns a new reference. 134 PyObject* FindExtensionByName(PyDescriptorPool* self, PyObject* arg); 135 136 // Looks up an enum type by name. Returns a PyEnumDescriptor corresponding 137 // to the field on success, or NULL on failure. 138 // 139 // Returns a new reference. 140 PyObject* FindEnumTypeByName(PyDescriptorPool* self, PyObject* arg); 141 142 // Looks up a oneof by name. Returns a COneofDescriptor corresponding 143 // to the oneof on success, or NULL on failure. 144 // 145 // Returns a new reference. 146 PyObject* FindOneofByName(PyDescriptorPool* self, PyObject* arg); 147 148 } // namespace cdescriptor_pool 149 150 // Retrieve the global descriptor pool owned by the _message module. 151 // This is the one used by pb2.py generated modules. 152 // Returns a *borrowed* reference. 153 // "Default" pool used to register messages from _pb2.py modules. 154 PyDescriptorPool* GetDefaultDescriptorPool(); 155 156 // Retrieve the python descriptor pool owning a C++ descriptor pool. 157 // Returns a *borrowed* reference. 158 PyDescriptorPool* GetDescriptorPool_FromPool(const DescriptorPool* pool); 159 160 // Initialize objects used by this module. 161 bool InitDescriptorPool(); 162 163 } // namespace python 164 } // namespace protobuf 165 166 } // namespace google 167 #endif // GOOGLE_PROTOBUF_PYTHON_CPP_DESCRIPTOR_POOL_H__ 168