diff options
Diffstat (limited to 'src/upb_sink.h')
-rw-r--r-- | src/upb_sink.h | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/src/upb_sink.h b/src/upb_sink.h new file mode 100644 index 0000000..17e1e1d --- /dev/null +++ b/src/upb_sink.h @@ -0,0 +1,117 @@ +/* + * upb - a minimalist implementation of protocol buffers. + * + * Copyright (c) 2010 Joshua Haberman. See LICENSE for details. + * + * upb_sink is a general purpose interface for pushing the contents of a + * protobuf from one component to another in a streaming fashion. We call the + * component that calls a upb_sink a "source". By "pushing" we mean that the + * source calls into the sink; the opposite (where a sink calls into the + * source) is known as "pull". In the push model the source gets the main + * loop; in a pull model the sink does. + * + * This interface is used as general-purpose glue in upb. For example, the + * parser interface works by implementing a source. Likewise the serialization + * simply implements a sink. Copying one protobuf to another is just a matter + * of using one message as a source and another as a sink. + * + * In terms of efficiency, we would generally expect "push" to be faster if the + * source had more state to track, and "pull" to be faster if the sink had more + * state. The reason is that whoever has the main loop can keep state on the + * stack (and possibly even in callee-save registers), whereas the the + * component that is "called into" always needs to reload its state from + * memory. + * + * In terms of programming complexity, it is easier and simpler to have the + * main loop, because you can store state in local variables. + * + * So the assumption inherent in using the push model is that sources are + * generally more complicated and stateful than consumers. For example, in the + * parser case, it has to deal with malformed input and associated errors; in + * comparison, the serializer deals with known-good input. + */ + +#ifndef UPB_SINK_H +#define UPB_SINK_H + +#ifdef __cplusplus +extern "C" { +#endif + +// Each of the upb_sink callbacks returns a status of this type. +typedef enum { + // The normal case, where the consumer wants to continue consuming. + UPB_SINK_CONTINUE, + + // The consumer has consumed the current value, but it wants to stop for now. + // When the producer is next invoked, it should resume at the next value. + UPB_SINK_SUSPEND, + + // The consumer wants to skip to the end of the current submessage and + // continue consuming. If we are at the top-level, the rest of the + // data is discarded. + UPB_SINK_SKIP +} upb_sink_status; + + +typedef struct { + struct upb_sink_callbacks *vtbl; +} upb_sink; + +/* upb_sink callbacks *********************************************************/ + +// The value callback is called when a regular value (ie. not a string or +// submessage) is pushed. +typedef upb_sink_status (*upb_value_cb)(upb_sink *s, struct upb_fielddef *f, + union upb_value val); + +// The string callback is called when a string is pushed. "str" is the string +// in which the data lives, but it may contain more data than the effective +// string. "start" and "end" indicate the substring of "str" that is the +// effective string. If "start" is <0, this string is a continuation of the +// previous string for this field. If end > upb_strlen(str) then there is more +// data to follow for this string. "end" can also be used as a hint for how +// much data follows, but this is only a hint and is not guaranteed. +// +// The data is supplied this way to give you the opportunity to reference this +// data instead of copying it (perhaps using upb_strslice), or to minimize +// copying if it is unavoidable. +typedef upb_sink_status (*upb_str_cb)(upb_sink *s, struct upb_fielddef *f, + upb_strptr str, + int32_t start, uint32_t end); + +// The start and end callbacks are called when a submessage begins and ends, +// respectively. +typedef upb_sink_status (*upb_start_cb)(upb_sink *s, struct upb_fielddef *f); +typedef upb_sink_status (*upb_end_cb)(upb_sink *s); + + +/* upb_sink implementation *************************************************/ + +typedef struct upb_sink_callbacks { + upb_value_cb value_cb; + upb_str_cb str_cb; + upb_start_cb start_cb; + upb_end_cb end_cb; +} upb_sink_callbacks; + +// We could potentially define these later to also be capable of calling a C++ +// virtual method instead of doing the virtual dispatch manually. This would +// make it possible to write C++ sinks in a more natural style. We could have +// a flag in upb_sink defining whether it is a C sink or a C++ one. +#define upb_sink_onvalue(s, f, val) s->vtbl->value_cb(s, f, val) +#define upb_sink_onstr(s, f, str, start, end) s->vtbl->str_cb(s, f, str, start, end) +#define upb_sink_onstart(s, f) s->vtbl->start_cb(s, f) +#define upb_sink_onend(s) s->vtbl->end_cb(s) + +// Initializes a plain C visitor with the given vtbl. The visitor must have +// been allocated separately. +INLINE void upb_sink_init(upb_sink *s, upb_sink_callbacks *vtbl) { + s->vtbl = vtbl; +} + +#ifdef __cplusplus +} /* extern "C" */ +#endif + +#endif |