Imported Upstream version 1.40.0
[platform/upstream/grpc.git] / third_party / upb / upb / handlers.h
1 /*
2 ** upb::Handlers (upb_handlers)
3 **
4 ** A upb_handlers is like a virtual table for a upb_msgdef.  Each field of the
5 ** message can have associated functions that will be called when we are
6 ** parsing or visiting a stream of data.  This is similar to how handlers work
7 ** in SAX (the Simple API for XML).
8 **
9 ** The handlers have no idea where the data is coming from, so a single set of
10 ** handlers could be used with two completely different data sources (for
11 ** example, a parser and a visitor over in-memory objects).  This decoupling is
12 ** the most important feature of upb, because it allows parsers and serializers
13 ** to be highly reusable.
14 **
15 ** This is a mixed C/C++ interface that offers a full API to both languages.
16 ** See the top-level README for more information.
17 */
18
19 #ifndef UPB_HANDLERS_H
20 #define UPB_HANDLERS_H
21
22 #include "upb/def.h"
23 #include "upb/table.int.h"
24
25 #include "upb/port_def.inc"
26
27 #ifdef __cplusplus
28 #include "upb/def.hpp"
29 namespace upb {
30 class HandlersPtr;
31 class HandlerCache;
32 template <class T> class Handler;
33 template <class T> struct CanonicalType;
34 }  /* namespace upb */
35 #endif
36
37
38 /* The maximum depth that the handler graph can have.  This is a resource limit
39  * for the C stack since we sometimes need to recursively traverse the graph.
40  * Cycles are ok; the traversal will stop when it detects a cycle, but we must
41  * hit the cycle before the maximum depth is reached.
42  *
43  * If having a single static limit is too inflexible, we can add another variant
44  * of Handlers::Freeze that allows specifying this as a parameter. */
45 #define UPB_MAX_HANDLER_DEPTH 64
46
47 /* All the different types of handlers that can be registered.
48  * Only needed for the advanced functions in upb::Handlers. */
49 typedef enum {
50   UPB_HANDLER_INT32,
51   UPB_HANDLER_INT64,
52   UPB_HANDLER_UINT32,
53   UPB_HANDLER_UINT64,
54   UPB_HANDLER_FLOAT,
55   UPB_HANDLER_DOUBLE,
56   UPB_HANDLER_BOOL,
57   UPB_HANDLER_STARTSTR,
58   UPB_HANDLER_STRING,
59   UPB_HANDLER_ENDSTR,
60   UPB_HANDLER_STARTSUBMSG,
61   UPB_HANDLER_ENDSUBMSG,
62   UPB_HANDLER_STARTSEQ,
63   UPB_HANDLER_ENDSEQ
64 } upb_handlertype_t;
65
66 #define UPB_HANDLER_MAX (UPB_HANDLER_ENDSEQ+1)
67
68 #define UPB_BREAK NULL
69
70 /* A convenient definition for when no closure is needed. */
71 extern char _upb_noclosure;
72 #define UPB_NO_CLOSURE &_upb_noclosure
73
74 /* A selector refers to a specific field handler in the Handlers object
75  * (for example: the STARTSUBMSG handler for field "field15"). */
76 typedef int32_t upb_selector_t;
77
78 /* Static selectors for upb::Handlers. */
79 #define UPB_STARTMSG_SELECTOR 0
80 #define UPB_ENDMSG_SELECTOR 1
81 #define UPB_UNKNOWN_SELECTOR 2
82 #define UPB_STATIC_SELECTOR_COUNT 3  /* Warning: also in upb/def.c. */
83
84 /* Static selectors for upb::BytesHandler. */
85 #define UPB_STARTSTR_SELECTOR 0
86 #define UPB_STRING_SELECTOR 1
87 #define UPB_ENDSTR_SELECTOR 2
88
89 #ifdef __cplusplus
90 template<class T> const void *UniquePtrForType() {
91   static const char ch = 0;
92   return &ch;
93 }
94 #endif
95
96 /* upb_handlers ************************************************************/
97
98 /* Handler attributes, to be registered with the handler itself. */
99 typedef struct {
100   const void *handler_data;
101   const void *closure_type;
102   const void *return_closure_type;
103   bool alwaysok;
104 } upb_handlerattr;
105
106 #define UPB_HANDLERATTR_INIT {NULL, NULL, NULL, false}
107
108 /* Bufhandle, data passed along with a buffer to indicate its provenance. */
109 struct upb_bufhandle {
110   /* The beginning of the buffer.  This may be different than the pointer
111    * passed to a StringBuf handler because the handler may receive data
112    * that is from the middle or end of a larger buffer. */
113   const char *buf;
114
115   /* The offset within the attached object where this buffer begins.  Only
116    * meaningful if there is an attached object. */
117   size_t objofs;
118
119   /* The attached object (if any) and a pointer representing its type. */
120   const void *obj;
121   const void *objtype;
122
123 #ifdef __cplusplus
124   template <class T>
125   void SetAttachedObject(const T* _obj) {
126     obj = _obj;
127     objtype = UniquePtrForType<T>();
128   }
129
130   template <class T>
131   const T *GetAttachedObject() const {
132     return objtype == UniquePtrForType<T>() ? static_cast<const T *>(obj)
133                                             : NULL;
134   }
135 #endif
136 };
137
138 typedef struct upb_bufhandle upb_bufhandle;
139
140 #define UPB_BUFHANDLE_INIT {NULL, 0, NULL, NULL}
141
142 /* Handler function typedefs. */
143 typedef void upb_handlerfree(void *d);
144 typedef bool upb_unknown_handlerfunc(void *c, const void *hd, const char *buf,
145                                      size_t n);
146 typedef bool upb_startmsg_handlerfunc(void *c, const void*);
147 typedef bool upb_endmsg_handlerfunc(void *c, const void *, upb_status *status);
148 typedef void* upb_startfield_handlerfunc(void *c, const void *hd);
149 typedef bool upb_endfield_handlerfunc(void *c, const void *hd);
150 typedef bool upb_int32_handlerfunc(void *c, const void *hd, int32_t val);
151 typedef bool upb_int64_handlerfunc(void *c, const void *hd, int64_t val);
152 typedef bool upb_uint32_handlerfunc(void *c, const void *hd, uint32_t val);
153 typedef bool upb_uint64_handlerfunc(void *c, const void *hd, uint64_t val);
154 typedef bool upb_float_handlerfunc(void *c, const void *hd, float val);
155 typedef bool upb_double_handlerfunc(void *c, const void *hd, double val);
156 typedef bool upb_bool_handlerfunc(void *c, const void *hd, bool val);
157 typedef void *upb_startstr_handlerfunc(void *c, const void *hd,
158                                        size_t size_hint);
159 typedef size_t upb_string_handlerfunc(void *c, const void *hd, const char *buf,
160                                       size_t n, const upb_bufhandle* handle);
161
162 struct upb_handlers;
163 typedef struct upb_handlers upb_handlers;
164
165 #ifdef __cplusplus
166 extern "C" {
167 #endif
168
169 /* Mutating accessors. */
170 const upb_status *upb_handlers_status(upb_handlers *h);
171 void upb_handlers_clearerr(upb_handlers *h);
172 const upb_msgdef *upb_handlers_msgdef(const upb_handlers *h);
173 bool upb_handlers_addcleanup(upb_handlers *h, void *p, upb_handlerfree *hfree);
174 bool upb_handlers_setunknown(upb_handlers *h, upb_unknown_handlerfunc *func,
175                              const upb_handlerattr *attr);
176 bool upb_handlers_setstartmsg(upb_handlers *h, upb_startmsg_handlerfunc *func,
177                               const upb_handlerattr *attr);
178 bool upb_handlers_setendmsg(upb_handlers *h, upb_endmsg_handlerfunc *func,
179                             const upb_handlerattr *attr);
180 bool upb_handlers_setint32(upb_handlers *h, const upb_fielddef *f,
181                            upb_int32_handlerfunc *func,
182                            const upb_handlerattr *attr);
183 bool upb_handlers_setint64(upb_handlers *h, const upb_fielddef *f,
184                            upb_int64_handlerfunc *func,
185                            const upb_handlerattr *attr);
186 bool upb_handlers_setuint32(upb_handlers *h, const upb_fielddef *f,
187                             upb_uint32_handlerfunc *func,
188                             const upb_handlerattr *attr);
189 bool upb_handlers_setuint64(upb_handlers *h, const upb_fielddef *f,
190                             upb_uint64_handlerfunc *func,
191                             const upb_handlerattr *attr);
192 bool upb_handlers_setfloat(upb_handlers *h, const upb_fielddef *f,
193                            upb_float_handlerfunc *func,
194                            const upb_handlerattr *attr);
195 bool upb_handlers_setdouble(upb_handlers *h, const upb_fielddef *f,
196                             upb_double_handlerfunc *func,
197                             const upb_handlerattr *attr);
198 bool upb_handlers_setbool(upb_handlers *h, const upb_fielddef *f,
199                           upb_bool_handlerfunc *func,
200                           const upb_handlerattr *attr);
201 bool upb_handlers_setstartstr(upb_handlers *h, const upb_fielddef *f,
202                               upb_startstr_handlerfunc *func,
203                               const upb_handlerattr *attr);
204 bool upb_handlers_setstring(upb_handlers *h, const upb_fielddef *f,
205                             upb_string_handlerfunc *func,
206                             const upb_handlerattr *attr);
207 bool upb_handlers_setendstr(upb_handlers *h, const upb_fielddef *f,
208                             upb_endfield_handlerfunc *func,
209                             const upb_handlerattr *attr);
210 bool upb_handlers_setstartseq(upb_handlers *h, const upb_fielddef *f,
211                               upb_startfield_handlerfunc *func,
212                               const upb_handlerattr *attr);
213 bool upb_handlers_setstartsubmsg(upb_handlers *h, const upb_fielddef *f,
214                                  upb_startfield_handlerfunc *func,
215                                  const upb_handlerattr *attr);
216 bool upb_handlers_setendsubmsg(upb_handlers *h, const upb_fielddef *f,
217                                upb_endfield_handlerfunc *func,
218                                const upb_handlerattr *attr);
219 bool upb_handlers_setendseq(upb_handlers *h, const upb_fielddef *f,
220                             upb_endfield_handlerfunc *func,
221                             const upb_handlerattr *attr);
222
223 /* Read-only accessors. */
224 const upb_handlers *upb_handlers_getsubhandlers(const upb_handlers *h,
225                                                 const upb_fielddef *f);
226 const upb_handlers *upb_handlers_getsubhandlers_sel(const upb_handlers *h,
227                                                     upb_selector_t sel);
228 upb_func *upb_handlers_gethandler(const upb_handlers *h, upb_selector_t s,
229                                   const void **handler_data);
230 bool upb_handlers_getattr(const upb_handlers *h, upb_selector_t s,
231                           upb_handlerattr *attr);
232
233 /* "Static" methods */
234 upb_handlertype_t upb_handlers_getprimitivehandlertype(const upb_fielddef *f);
235 bool upb_handlers_getselector(const upb_fielddef *f, upb_handlertype_t type,
236                               upb_selector_t *s);
237 UPB_INLINE upb_selector_t upb_handlers_getendselector(upb_selector_t start) {
238   return start + 1;
239 }
240
241 #ifdef __cplusplus
242 }  /* extern "C" */
243
244 namespace upb {
245 typedef upb_handlers Handlers;
246 }
247
248 /* Convenience macros for creating a Handler object that is wrapped with a
249  * type-safe wrapper function that converts the "void*" parameters/returns
250  * of the underlying C API into nice C++ function.
251  *
252  * Sample usage:
253  *   void OnValue1(MyClosure* c, const MyHandlerData* d, int32_t val) {
254  *     // do stuff ...
255  *   }
256  *
257  *   // Handler that doesn't need any data bound to it.
258  *   void OnValue2(MyClosure* c, int32_t val) {
259  *     // do stuff ...
260  *   }
261  *
262  *   // Handler that returns bool so it can return failure if necessary.
263  *   bool OnValue3(MyClosure* c, int32_t val) {
264  *     // do stuff ...
265  *     return ok;
266  *   }
267  *
268  *   // Member function handler.
269  *   class MyClosure {
270  *    public:
271  *     void OnValue(int32_t val) {
272  *       // do stuff ...
273  *     }
274  *   };
275  *
276  *   // Takes ownership of the MyHandlerData.
277  *   handlers->SetInt32Handler(f1, UpbBind(OnValue1, new MyHandlerData(...)));
278  *   handlers->SetInt32Handler(f2, UpbMakeHandler(OnValue2));
279  *   handlers->SetInt32Handler(f1, UpbMakeHandler(OnValue3));
280  *   handlers->SetInt32Handler(f2, UpbMakeHandler(&MyClosure::OnValue));
281  */
282
283 /* In C++11, the "template" disambiguator can appear even outside templates,
284  * so all calls can safely use this pair of macros. */
285
286 #define UpbMakeHandler(f) upb::MatchFunc(f).template GetFunc<f>()
287
288 /* We have to be careful to only evaluate "d" once. */
289 #define UpbBind(f, d) upb::MatchFunc(f).template GetFunc<f>((d))
290
291 /* Handler: a struct that contains the (handler, data, deleter) tuple that is
292  * used to register all handlers.  Users can Make() these directly but it's
293  * more convenient to use the UpbMakeHandler/UpbBind macros above. */
294 template <class T> class upb::Handler {
295  public:
296   /* The underlying, handler function signature that upb uses internally. */
297   typedef T FuncPtr;
298
299   /* Intentionally implicit. */
300   template <class F> Handler(F func);
301   ~Handler() { UPB_ASSERT(registered_); }
302
303   void AddCleanup(upb_handlers* h) const;
304   FuncPtr handler() const { return handler_; }
305   const upb_handlerattr& attr() const { return attr_; }
306
307  private:
308   Handler(const Handler&) = delete;
309   Handler& operator=(const Handler&) = delete;
310
311   FuncPtr handler_;
312   mutable upb_handlerattr attr_;
313   mutable bool registered_;
314   void *cleanup_data_;
315   upb_handlerfree *cleanup_func_;
316 };
317
318 /* A upb::Handlers object represents the set of handlers associated with a
319  * message in the graph of messages.  You can think of it as a big virtual
320  * table with functions corresponding to all the events that can fire while
321  * parsing or visiting a message of a specific type.
322  *
323  * Any handlers that are not set behave as if they had successfully consumed
324  * the value.  Any unset Start* handlers will propagate their closure to the
325  * inner frame.
326  *
327  * The easiest way to create the *Handler objects needed by the Set* methods is
328  * with the UpbBind() and UpbMakeHandler() macros; see below. */
329 class upb::HandlersPtr {
330  public:
331   HandlersPtr(upb_handlers* ptr) : ptr_(ptr) {}
332
333   upb_handlers* ptr() const { return ptr_; }
334
335   typedef upb_selector_t Selector;
336   typedef upb_handlertype_t Type;
337
338   typedef Handler<void *(*)(void *, const void *)> StartFieldHandler;
339   typedef Handler<bool (*)(void *, const void *)> EndFieldHandler;
340   typedef Handler<bool (*)(void *, const void *)> StartMessageHandler;
341   typedef Handler<bool (*)(void *, const void *, upb_status *)>
342       EndMessageHandler;
343   typedef Handler<void *(*)(void *, const void *, size_t)> StartStringHandler;
344   typedef Handler<size_t (*)(void *, const void *, const char *, size_t,
345                              const upb_bufhandle *)>
346       StringHandler;
347
348   template <class T> struct ValueHandler {
349     typedef Handler<bool(*)(void *, const void *, T)> H;
350   };
351
352   typedef ValueHandler<int32_t>::H     Int32Handler;
353   typedef ValueHandler<int64_t>::H     Int64Handler;
354   typedef ValueHandler<uint32_t>::H    UInt32Handler;
355   typedef ValueHandler<uint64_t>::H    UInt64Handler;
356   typedef ValueHandler<float>::H       FloatHandler;
357   typedef ValueHandler<double>::H      DoubleHandler;
358   typedef ValueHandler<bool>::H        BoolHandler;
359
360   /* Any function pointer can be converted to this and converted back to its
361    * correct type. */
362   typedef void GenericFunction();
363
364   typedef void HandlersCallback(const void *closure, upb_handlers *h);
365
366   /* Returns the msgdef associated with this handlers object. */
367   MessageDefPtr message_def() const {
368     return MessageDefPtr(upb_handlers_msgdef(ptr()));
369   }
370
371   /* Adds the given pointer and function to the list of cleanup functions that
372    * will be run when these handlers are freed.  If this pointer has previously
373    * been registered, the function returns false and does nothing. */
374   bool AddCleanup(void *ptr, upb_handlerfree *cleanup) {
375     return upb_handlers_addcleanup(ptr_, ptr, cleanup);
376   }
377
378   /* Sets the startmsg handler for the message, which is defined as follows:
379    *
380    *   bool startmsg(MyType* closure) {
381    *     // Called when the message begins.  Returns true if processing should
382    *     // continue.
383    *     return true;
384    *   }
385    */
386   bool SetStartMessageHandler(const StartMessageHandler &h) {
387     h.AddCleanup(ptr());
388     return upb_handlers_setstartmsg(ptr(), h.handler(), &h.attr());
389   }
390
391   /* Sets the endmsg handler for the message, which is defined as follows:
392    *
393    *   bool endmsg(MyType* closure, upb_status *status) {
394    *     // Called when processing of this message ends, whether in success or
395    *     // failure.  "status" indicates the final status of processing, and
396    *     // can also be modified in-place to update the final status.
397    *   }
398    */
399   bool SetEndMessageHandler(const EndMessageHandler& h) {
400     h.AddCleanup(ptr());
401     return upb_handlers_setendmsg(ptr(), h.handler(), &h.attr());
402   }
403
404   /* Sets the value handler for the given field, which is defined as follows
405    * (this is for an int32 field; other field types will pass their native
406    * C/C++ type for "val"):
407    *
408    *   bool OnValue(MyClosure* c, const MyHandlerData* d, int32_t val) {
409    *     // Called when the field's value is encountered.  "d" contains
410    *     // whatever data was bound to this field when it was registered.
411    *     // Returns true if processing should continue.
412    *     return true;
413    *   }
414    *
415    *   handers->SetInt32Handler(f, UpbBind(OnValue, new MyHandlerData(...)));
416    *
417    * The value type must exactly match f->type().
418    * For example, a handler that takes an int32_t parameter may only be used for
419    * fields of type UPB_TYPE_INT32 and UPB_TYPE_ENUM.
420    *
421    * Returns false if the handler failed to register; in this case the cleanup
422    * handler (if any) will be called immediately.
423    */
424   bool SetInt32Handler(FieldDefPtr f, const Int32Handler &h) {
425     h.AddCleanup(ptr());
426     return upb_handlers_setint32(ptr(), f.ptr(), h.handler(), &h.attr());
427   }
428
429   bool SetInt64Handler (FieldDefPtr f,  const Int64Handler& h) {
430     h.AddCleanup(ptr());
431     return upb_handlers_setint64(ptr(), f.ptr(), h.handler(), &h.attr());
432   }
433
434   bool SetUInt32Handler(FieldDefPtr f, const UInt32Handler& h) {
435     h.AddCleanup(ptr());
436     return upb_handlers_setuint32(ptr(), f.ptr(), h.handler(), &h.attr());
437   }
438
439   bool SetUInt64Handler(FieldDefPtr f, const UInt64Handler& h) {
440     h.AddCleanup(ptr());
441     return upb_handlers_setuint64(ptr(), f.ptr(), h.handler(), &h.attr());
442   }
443
444   bool SetFloatHandler (FieldDefPtr f,  const FloatHandler& h) {
445     h.AddCleanup(ptr());
446     return upb_handlers_setfloat(ptr(), f.ptr(), h.handler(), &h.attr());
447   }
448
449   bool SetDoubleHandler(FieldDefPtr f, const DoubleHandler& h) {
450     h.AddCleanup(ptr());
451     return upb_handlers_setdouble(ptr(), f.ptr(), h.handler(), &h.attr());
452   }
453
454   bool SetBoolHandler(FieldDefPtr f, const BoolHandler &h) {
455     h.AddCleanup(ptr());
456     return upb_handlers_setbool(ptr(), f.ptr(), h.handler(), &h.attr());
457   }
458
459   /* Like the previous, but templated on the type on the value (ie. int32).
460    * This is mostly useful to call from other templates.  To call this you must
461    * specify the template parameter explicitly, ie:
462    *   h->SetValueHandler<T>(f, UpbBind(MyHandler<T>, MyData)); */
463   template <class T>
464   bool SetValueHandler(
465       FieldDefPtr f,
466       const typename ValueHandler<typename CanonicalType<T>::Type>::H &handler);
467
468   /* Sets handlers for a string field, which are defined as follows:
469    *
470    *   MySubClosure* startstr(MyClosure* c, const MyHandlerData* d,
471    *                          size_t size_hint) {
472    *     // Called when a string value begins.  The return value indicates the
473    *     // closure for the string.  "size_hint" indicates the size of the
474    *     // string if it is known, however if the string is length-delimited
475    *     // and the end-of-string is not available size_hint will be zero.
476    *     // This case is indistinguishable from the case where the size is
477    *     // known to be zero.
478    *     //
479    *     // TODO(haberman): is it important to distinguish these cases?
480    *     // If we had ssize_t as a type we could make -1 "unknown", but
481    *     // ssize_t is POSIX (not ANSI) and therefore less portable.
482    *     // In practice I suspect it won't be important to distinguish.
483    *     return closure;
484    *   }
485    *
486    *   size_t str(MyClosure* closure, const MyHandlerData* d,
487    *              const char *str, size_t len) {
488    *     // Called for each buffer of string data; the multiple physical buffers
489    *     // are all part of the same logical string.  The return value indicates
490    *     // how many bytes were consumed.  If this number is less than "len",
491    *     // this will also indicate that processing should be halted for now,
492    *     // like returning false or UPB_BREAK from any other callback.  If
493    *     // number is greater than "len", the excess bytes will be skipped over
494    *     // and not passed to the callback.
495    *     return len;
496    *   }
497    *
498    *   bool endstr(MyClosure* c, const MyHandlerData* d) {
499    *     // Called when a string value ends.  Return value indicates whether
500    *     // processing should continue.
501    *     return true;
502    *   }
503    */
504   bool SetStartStringHandler(FieldDefPtr f, const StartStringHandler &h) {
505     h.AddCleanup(ptr());
506     return upb_handlers_setstartstr(ptr(), f.ptr(), h.handler(), &h.attr());
507   }
508
509   bool SetStringHandler(FieldDefPtr f, const StringHandler& h) {
510     h.AddCleanup(ptr());
511     return upb_handlers_setstring(ptr(), f.ptr(), h.handler(), &h.attr());
512   }
513
514   bool SetEndStringHandler(FieldDefPtr f, const EndFieldHandler& h) {
515     h.AddCleanup(ptr());
516     return upb_handlers_setendstr(ptr(), f.ptr(), h.handler(), &h.attr());
517   }
518
519   /* Sets the startseq handler, which is defined as follows:
520    *
521    *   MySubClosure *startseq(MyClosure* c, const MyHandlerData* d) {
522    *     // Called when a sequence (repeated field) begins.  The returned
523    *     // pointer indicates the closure for the sequence (or UPB_BREAK
524    *     // to interrupt processing).
525    *     return closure;
526    *   }
527    *
528    *   h->SetStartSequenceHandler(f, UpbBind(startseq, new MyHandlerData(...)));
529    *
530    * Returns "false" if "f" does not belong to this message or is not a
531    * repeated field.
532    */
533   bool SetStartSequenceHandler(FieldDefPtr f, const StartFieldHandler &h) {
534     h.AddCleanup(ptr());
535     return upb_handlers_setstartseq(ptr(), f.ptr(), h.handler(), &h.attr());
536   }
537
538   /* Sets the startsubmsg handler for the given field, which is defined as
539    * follows:
540    *
541    *   MySubClosure* startsubmsg(MyClosure* c, const MyHandlerData* d) {
542    *     // Called when a submessage begins.  The returned pointer indicates the
543    *     // closure for the sequence (or UPB_BREAK to interrupt processing).
544    *     return closure;
545    *   }
546    *
547    *   h->SetStartSubMessageHandler(f, UpbBind(startsubmsg,
548    *                                           new MyHandlerData(...)));
549    *
550    * Returns "false" if "f" does not belong to this message or is not a
551    * submessage/group field.
552    */
553   bool SetStartSubMessageHandler(FieldDefPtr f, const StartFieldHandler& h) {
554     h.AddCleanup(ptr());
555     return upb_handlers_setstartsubmsg(ptr(), f.ptr(), h.handler(), &h.attr());
556   }
557
558   /* Sets the endsubmsg handler for the given field, which is defined as
559    * follows:
560    *
561    *   bool endsubmsg(MyClosure* c, const MyHandlerData* d) {
562    *     // Called when a submessage ends.  Returns true to continue processing.
563    *     return true;
564    *   }
565    *
566    * Returns "false" if "f" does not belong to this message or is not a
567    * submessage/group field.
568    */
569   bool SetEndSubMessageHandler(FieldDefPtr f, const EndFieldHandler &h) {
570     h.AddCleanup(ptr());
571     return upb_handlers_setendsubmsg(ptr(), f.ptr(), h.handler(), &h.attr());
572   }
573
574   /* Starts the endsubseq handler for the given field, which is defined as
575    * follows:
576    *
577    *   bool endseq(MyClosure* c, const MyHandlerData* d) {
578    *     // Called when a sequence ends.  Returns true continue processing.
579    *     return true;
580    *   }
581    *
582    * Returns "false" if "f" does not belong to this message or is not a
583    * repeated field.
584    */
585   bool SetEndSequenceHandler(FieldDefPtr f, const EndFieldHandler &h) {
586     h.AddCleanup(ptr());
587     return upb_handlers_setendseq(ptr(), f.ptr(), h.handler(), &h.attr());
588   }
589
590  private:
591   upb_handlers* ptr_;
592 };
593
594 #endif  /* __cplusplus */
595
596 /* upb_handlercache ***********************************************************/
597
598 /* A upb_handlercache lazily builds and caches upb_handlers.  You pass it a
599  * function (with optional closure) that can build handlers for a given
600  * message on-demand, and the cache maintains a map of msgdef->handlers. */
601
602 #ifdef __cplusplus
603 extern "C" {
604 #endif
605
606 struct upb_handlercache;
607 typedef struct upb_handlercache upb_handlercache;
608
609 typedef void upb_handlers_callback(const void *closure, upb_handlers *h);
610
611 upb_handlercache *upb_handlercache_new(upb_handlers_callback *callback,
612                                        const void *closure);
613 void upb_handlercache_free(upb_handlercache *cache);
614 const upb_handlers *upb_handlercache_get(upb_handlercache *cache,
615                                          const upb_msgdef *md);
616 bool upb_handlercache_addcleanup(upb_handlercache *h, void *p,
617                                  upb_handlerfree *hfree);
618
619 #ifdef __cplusplus
620 }  /* extern "C" */
621
622 class upb::HandlerCache {
623  public:
624   HandlerCache(upb_handlers_callback *callback, const void *closure)
625       : ptr_(upb_handlercache_new(callback, closure), upb_handlercache_free) {}
626   HandlerCache(HandlerCache&&) = default;
627   HandlerCache& operator=(HandlerCache&&) = default;
628   HandlerCache(upb_handlercache* c) : ptr_(c, upb_handlercache_free) {}
629
630   upb_handlercache* ptr() { return ptr_.get(); }
631
632   const upb_handlers *Get(MessageDefPtr md) {
633     return upb_handlercache_get(ptr_.get(), md.ptr());
634   }
635
636  private:
637   std::unique_ptr<upb_handlercache, decltype(&upb_handlercache_free)> ptr_;
638 };
639
640 #endif  /* __cplusplus */
641
642 /* upb_byteshandler ***********************************************************/
643
644 typedef struct {
645   upb_func *func;
646
647   /* It is wasteful to include the entire attributes here:
648    *
649    * * Some of the information is redundant (like storing the closure type
650    *   separately for each handler that must match).
651    * * Some of the info is only needed prior to freeze() (like closure types).
652    * * alignment padding wastes a lot of space for alwaysok_.
653    *
654    * If/when the size and locality of handlers is an issue, we can optimize this
655    * not to store the entire attr like this.  We do not expose the table's
656    * layout to allow this optimization in the future. */
657   upb_handlerattr attr;
658 } upb_handlers_tabent;
659
660 #define UPB_TABENT_INIT {NULL, UPB_HANDLERATTR_INIT}
661
662 typedef struct {
663   upb_handlers_tabent table[3];
664 } upb_byteshandler;
665
666 #define UPB_BYTESHANDLER_INIT                             \
667   {                                                       \
668     { UPB_TABENT_INIT, UPB_TABENT_INIT, UPB_TABENT_INIT } \
669   }
670
671 UPB_INLINE void upb_byteshandler_init(upb_byteshandler *handler) {
672   upb_byteshandler init = UPB_BYTESHANDLER_INIT;
673   *handler = init;
674 }
675
676 #ifdef __cplusplus
677 extern "C" {
678 #endif
679
680 /* Caller must ensure that "d" outlives the handlers. */
681 bool upb_byteshandler_setstartstr(upb_byteshandler *h,
682                                   upb_startstr_handlerfunc *func, void *d);
683 bool upb_byteshandler_setstring(upb_byteshandler *h,
684                                 upb_string_handlerfunc *func, void *d);
685 bool upb_byteshandler_setendstr(upb_byteshandler *h,
686                                 upb_endfield_handlerfunc *func, void *d);
687
688 #ifdef __cplusplus
689 }  /* extern "C" */
690
691 namespace upb {
692 typedef upb_byteshandler BytesHandler;
693 }
694 #endif
695
696 /** Message handlers ******************************************************************/
697
698 #ifdef __cplusplus
699 extern "C" {
700 #endif
701
702 /* These are the handlers used internally by upb_msgfactory_getmergehandlers().
703  * They write scalar data to a known offset from the message pointer.
704  *
705  * These would be trivial for anyone to implement themselves, but it's better
706  * to use these because some JITs will recognize and specialize these instead
707  * of actually calling the function. */
708
709 /* Sets a handler for the given primitive field that will write the data at the
710  * given offset.  If hasbit > 0, also sets a hasbit at the given bit offset
711  * (addressing each byte low to high). */
712 bool upb_msg_setscalarhandler(upb_handlers *h,
713                               const upb_fielddef *f,
714                               size_t offset,
715                               int32_t hasbit);
716
717 /* If the given handler is a msghandlers_primitive field, returns true and sets
718  * *type, *offset and *hasbit.  Otherwise returns false. */
719 bool upb_msg_getscalarhandlerdata(const upb_handlers *h,
720                                   upb_selector_t s,
721                                   upb_fieldtype_t *type,
722                                   size_t *offset,
723                                   int32_t *hasbit);
724
725
726
727 #ifdef __cplusplus
728 }  /* extern "C" */
729 #endif
730
731 #include "upb/port_undef.inc"
732
733 #include "upb/handlers-inl.h"
734
735 #endif  /* UPB_HANDLERS_H */