diff options
author | Joshua Haberman <jhaberman@gmail.com> | 2019-05-15 14:00:56 -0700 |
---|---|---|
committer | Joshua Haberman <jhaberman@gmail.com> | 2019-05-15 14:00:56 -0700 |
commit | 4d89a44b2626ca52998344b95f6f86ea068c4e56 (patch) | |
tree | caeff10d42a7ced0f6f7a474db122251131d9e3d | |
parent | ae107c7ab983f22791897569ec7b8356e76d72fb (diff) |
Some revisions to README.md and DESIGN.md.
-rw-r--r-- | DESIGN.md | 33 | ||||
-rw-r--r-- | README.md | 15 |
2 files changed, 16 insertions, 32 deletions
@@ -2,9 +2,6 @@ μpb Design ---------- -**NOTE:** the design described here is being implemented currently, but is not -yet complete. The repo is in heavy transition right now. - μpb has the following design goals: - C89 compatible. @@ -62,22 +59,14 @@ link μpb will never need to worry about this. TODO ---- -The current state of the repo is quite different than what is described above. -Here are the major items that need to be implemented. - -1. implement the core generic protobuf binary encoder/decoder that uses a - `upb_msglayout*`. -2. remove all mention of handlers, sink, etc. from core into their own module. - All of the handlers stuff needs substantial revision, but moving it out of - core is the first priority. -3. move all of the def/refcounted stuff out of core. The defs also need - substantial revision, but moving them out of core is the first priority. -4. revise our generated code until it is in a state where we feel comfortable - committing to API/ABI stability for it. This may involve moving different - parts of the generated code into separate files, like keeping the serialized - descriptor in a separate file from the compact msglayout. -5. revise all of the existing encoders/decoders and handlers. We probably - will want to keep handlers, since they let us decouple encoders/decoders - from `upb_msg`, but we need to simplify all of that a LOT. Likely we will - want to make handlers only per-message instead of per-field, except for - variable-length fields. +1. revise our generated code until it is in a state where we feel comfortable + committing to API/ABI stability for it. In particular there is an open + question of whether non-ABI-compatible field accesses should have a + fastpath different from the ABI-compatible field access. +1. Add missing features (maps, extensions, unknown fields). +1. Flesh out C++ wrappers. +1. *(lower-priority)*: revise all of the existing encoders/decoders and + handlers. We probably will want to keep handlers, since they let us decouple + encoders/decoders from `upb_msg`, but we need to simplify all of that a LOT. + Likely we will want to make handlers only per-message instead of per-field, + except for variable-length fields. @@ -10,16 +10,16 @@ upb generates a C API for creating, parsing, and serializing messages as declared in `.proto` files. upb is heavily arena-based -- all -messages always live in an arena. You control where the arena gets -memory from, so the arena can come from stack memory, for example. -Here is a simple example (`ConformanceRequest` and `ConformanceResponse` -are generated message types): +messages always live in an arena (note: the arena can live in stack or +static memory if desired). Here is a simple example: ```c #include "conformance/conformance.upb.h" void foo(const char* data, size_t size) { upb_arena *arena; + + /* Generated message type. */ conformance_ConformanceRequest *request; conformance_ConformanceResponse *response; @@ -46,16 +46,11 @@ void foo(const char* data, size_t size) { } } + /* Frees all messages on the arena. */ upb_arena_free(arena); } ``` -Messages are opaque, so you always have to use generated getter/setter -methods to read/write fields. This is somewhat unfortunate for C -because the function names are long, but this is necessary to provide -correct semantics for oneof fields, proto2 presence, etc. It is also -necessary for providing a stable ABI, in cases where that is desired. - API and ABI are both subject to change! Please do not distribute as a shared library for this reason (for now at least). |