diff options
Diffstat (limited to 'upb/upb.h')
| -rw-r--r-- | upb/upb.h | 552 |
1 files changed, 374 insertions, 178 deletions
@@ -13,6 +13,18 @@ #include <stdbool.h> #include <stddef.h> +#ifdef __cplusplus +namespace upb { +class Allocator; +class Arena; +class Environment; +class ErrorSpace; +class Status; +template <int N> class InlinedArena; +template <int N> class InlinedEnvironment; +} +#endif + /* UPB_INLINE: inline if possible, emit standalone code if required. */ #ifdef __cplusplus #define UPB_INLINE inline @@ -80,6 +92,7 @@ #define UPB_ASSERT_STDLAYOUT(type) \ static_assert(std::is_standard_layout<type>::value, \ #type " must be standard layout"); +#define UPB_FINAL final #else /* !defined(UPB_CXX11) */ #define UPB_DISALLOW_COPY_AND_ASSIGN(class_name) \ class_name(const class_name&); \ @@ -89,6 +102,7 @@ ~class_name(); \ UPB_DISALLOW_COPY_AND_ASSIGN(class_name) #define UPB_ASSERT_STDLAYOUT(type) +#define UPB_FINAL #endif /* UPB_DECLARE_TYPE() @@ -190,6 +204,7 @@ /* Generic function type. */ typedef void upb_func(); + /* C++ Casts ******************************************************************/ #ifdef __cplusplus @@ -267,247 +282,428 @@ class PointerBase2 : public PointerBase<T, Base> { #endif -/* upb::reffed_ptr ************************************************************/ +/* upb::ErrorSpace ************************************************************/ + +/* A upb::ErrorSpace represents some domain of possible error values. This lets + * upb::Status attach specific error codes to operations, like POSIX/C errno, + * Win32 error codes, etc. Clients who want to know the very specific error + * code can check the error space and then know the type of the integer code. + * + * NOTE: upb::ErrorSpace is currently not used and should be considered + * experimental. It is important primarily in cases where upb is performing + * I/O, but upb doesn't currently have any components that do this. */ + +UPB_DECLARE_TYPE(upb::ErrorSpace, upb_errorspace) #ifdef __cplusplus +class upb::ErrorSpace { +#else +struct upb_errorspace { +#endif + const char *name; +}; -#include <algorithm> /* For std::swap(). */ -namespace upb { +/* upb::Status ****************************************************************/ + +/* upb::Status represents a success or failure status and error message. + * It owns no resources and allocates no memory, so it should work + * even in OOM situations. */ +UPB_DECLARE_TYPE(upb::Status, upb_status) + +/* The maximum length of an error message before it will get truncated. */ +#define UPB_STATUS_MAX_MESSAGE 128 -/* Provides RAII semantics for upb refcounted objects. Each reffed_ptr owns a - * ref on whatever object it points to (if any). */ -template <class T> class reffed_ptr { +UPB_BEGIN_EXTERN_C + +const char *upb_status_errmsg(const upb_status *status); +bool upb_ok(const upb_status *status); +upb_errorspace *upb_status_errspace(const upb_status *status); +int upb_status_errcode(const upb_status *status); + +/* Any of the functions that write to a status object allow status to be NULL, + * to support use cases where the function's caller does not care about the + * status message. */ +void upb_status_clear(upb_status *status); +void upb_status_seterrmsg(upb_status *status, const char *msg); +void upb_status_seterrf(upb_status *status, const char *fmt, ...); +void upb_status_vseterrf(upb_status *status, const char *fmt, va_list args); +void upb_status_copy(upb_status *to, const upb_status *from); + +UPB_END_EXTERN_C + +#ifdef __cplusplus + +class upb::Status { public: - reffed_ptr() : ptr_(NULL) {} - - /* If ref_donor is NULL, takes a new ref, otherwise adopts from ref_donor. */ - template <class U> - reffed_ptr(U* val, const void* ref_donor = NULL) - : ptr_(upb::upcast(val)) { - if (ref_donor) { - assert(ptr_); - ptr_->DonateRef(ref_donor, this); - } else if (ptr_) { - ptr_->Ref(this); - } - } + Status() { upb_status_clear(this); } - template <class U> - reffed_ptr(const reffed_ptr<U>& other) - : ptr_(upb::upcast(other.get())) { - if (ptr_) ptr_->Ref(this); - } + /* Returns true if there is no error. */ + bool ok() const { return upb_ok(this); } - reffed_ptr(const reffed_ptr& other) - : ptr_(upb::upcast(other.get())) { - if (ptr_) ptr_->Ref(this); - } + /* Optional error space and code, useful if the caller wants to + * programmatically check the specific kind of error. */ + ErrorSpace* error_space() { return upb_status_errspace(this); } + int error_code() const { return upb_status_errcode(this); } - ~reffed_ptr() { if (ptr_) ptr_->Unref(this); } + /* The returned string is invalidated by any other call into the status. */ + const char *error_message() const { return upb_status_errmsg(this); } - template <class U> - reffed_ptr& operator=(const reffed_ptr<U>& other) { - reset(other.get()); - return *this; + /* The error message will be truncated if it is longer than + * UPB_STATUS_MAX_MESSAGE-4. */ + void SetErrorMessage(const char* msg) { upb_status_seterrmsg(this, msg); } + void SetFormattedErrorMessage(const char* fmt, ...) { + va_list args; + va_start(args, fmt); + upb_status_vseterrf(this, fmt, args); + va_end(args); } - reffed_ptr& operator=(const reffed_ptr& other) { - reset(other.get()); - return *this; - } + /* Resets the status to a successful state with no message. */ + void Clear() { upb_status_clear(this); } - /* TODO(haberman): add C++11 move construction/assignment for greater - * efficiency. */ + void CopyFrom(const Status& other) { upb_status_copy(this, &other); } - void swap(reffed_ptr& other) { - if (ptr_ == other.ptr_) { - return; - } + private: + UPB_DISALLOW_COPY_AND_ASSIGN(Status) +#else +struct upb_status { +#endif + bool ok_; - if (ptr_) ptr_->DonateRef(this, &other); - if (other.ptr_) other.ptr_->DonateRef(&other, this); - std::swap(ptr_, other.ptr_); - } + /* Specific status code defined by some error space (optional). */ + int code_; + upb_errorspace *error_space_; - T& operator*() const { - assert(ptr_); - return *ptr_; - } + /* TODO(haberman): add file/line of error? */ - T* operator->() const { - assert(ptr_); - return ptr_; - } + /* Error message; NULL-terminated. */ + char msg[UPB_STATUS_MAX_MESSAGE]; +}; - T* get() const { return ptr_; } +#define UPB_STATUS_INIT {true, 0, NULL, {0}} - /* If ref_donor is NULL, takes a new ref, otherwise adopts from ref_donor. */ - template <class U> - void reset(U* ptr = NULL, const void* ref_donor = NULL) { - reffed_ptr(ptr, ref_donor).swap(*this); - } - template <class U> - reffed_ptr<U> down_cast() { - return reffed_ptr<U>(upb::down_cast<U*>(get())); - } +/** Built-in error spaces. ****************************************************/ - template <class U> - reffed_ptr<U> dyn_cast() { - return reffed_ptr<U>(upb::dyn_cast<U*>(get())); - } +/* Errors raised by upb that we want to be able to detect programmatically. */ +typedef enum { + UPB_NOMEM /* Can't reuse ENOMEM because it is POSIX, not ISO C. */ +} upb_errcode_t; - /* Plain release() is unsafe; if we were the only owner, it would leak the - * object. Instead we provide this: */ - T* ReleaseTo(const void* new_owner) { - T* ret = NULL; - ptr_->DonateRef(this, new_owner); - std::swap(ret, ptr_); - return ret; - } +extern upb_errorspace upb_upberr; + +void upb_upberr_setoom(upb_status *s); + +/* Since errno is defined by standard C, we define an error space for it in + * core upb. Other error spaces should be defined in other, platform-specific + * modules. */ + +extern upb_errorspace upb_errnoerr; + + +/** upb::Allocator ************************************************************/ + +/* A upb::Allocator is a possibly-stateful allocator object. + * + * It could either be an arena allocator (which doesn't require individual + * free() calls) or a regular malloc() (which does). The client must therefore + * free memory unless it knows that the allocator is an arena allocator. */ +UPB_DECLARE_TYPE(upb::Allocator, upb_alloc) + +/* A malloc()/free() function. + * If "size" is 0 then the function acts like free(), otherwise it acts like + * realloc(). Only "oldsize" bytes from a previous allocation are preserved. */ +typedef void *upb_alloc_func(upb_alloc *alloc, void *ptr, size_t oldsize, + size_t size); + +#ifdef __cplusplus + +class upb::Allocator UPB_FINAL { + public: + Allocator() {} private: - T* ptr_; + UPB_DISALLOW_COPY_AND_ASSIGN(Allocator) + + public: +#else +struct upb_alloc { +#endif /* __cplusplus */ + upb_alloc_func *func; }; -} /* namespace upb */ +UPB_INLINE void *upb_malloc(upb_alloc *alloc, size_t size) { + assert(size > 0); + return alloc->func(alloc, NULL, 0, size); +} -#endif /* __cplusplus */ +UPB_INLINE void *upb_realloc(upb_alloc *alloc, void *ptr, size_t oldsize, + size_t size) { + assert(size > 0); + return alloc->func(alloc, ptr, oldsize, size); +} +UPB_INLINE void upb_free(upb_alloc *alloc, void *ptr) { + alloc->func(alloc, ptr, 0, 0); +} -/* upb::Status ****************************************************************/ +/* The global allocator used by upb. Uses the standard malloc()/free(). */ -#ifdef __cplusplus -namespace upb { -class ErrorSpace; -class Status; +extern upb_alloc upb_alloc_global; + +/* Functions that hard-code the global malloc. + * + * We still get benefit because we can put custom logic into our global + * allocator, like injecting out-of-memory faults in debug/testing builds. */ + +UPB_INLINE void *upb_gmalloc(size_t size) { + return upb_malloc(&upb_alloc_global, size); } -#endif -UPB_DECLARE_TYPE(upb::ErrorSpace, upb_errorspace) -UPB_DECLARE_TYPE(upb::Status, upb_status) +UPB_INLINE void *upb_grealloc(void *ptr, size_t oldsize, size_t size) { + return upb_realloc(&upb_alloc_global, ptr, oldsize, size); +} -/* The maximum length of an error message before it will get truncated. */ -#define UPB_STATUS_MAX_MESSAGE 128 +UPB_INLINE void upb_gfree(void *ptr) { + upb_free(&upb_alloc_global, ptr); +} + +/* upb::Arena *****************************************************************/ + +/* upb::Arena is a specific allocator implementation that uses arena allocation. + * The user provides an allocator that will be used to allocate the underlying + * arena blocks. Arenas by nature do not require the individual allocations + * to be freed. However the Arena does allow users to register cleanup + * functions that will run when the arena is destroyed. + * + * A upb::Arena is *not* thread-safe. + * + * You could write a thread-safe arena allocator that satisfies the + * upb::Allocator interface, but it would not be as efficient for the + * single-threaded case. */ +UPB_DECLARE_TYPE(upb::Arena, upb_arena) + +typedef void upb_cleanup_func(void *ud); + +#define UPB_ARENA_BLOCK_OVERHEAD (sizeof(size_t)*4) + +UPB_BEGIN_EXTERN_C -/* An error callback function is used to report errors from some component. - * The function can return "true" to indicate that the component should try - * to recover and proceed, but this is not always possible. */ -typedef bool upb_errcb_t(void *closure, const upb_status* status); +void upb_arena_init(upb_arena *a); +void upb_arena_init2(upb_arena *a, void *mem, size_t n, upb_alloc *alloc); +void upb_arena_uninit(upb_arena *a); +upb_alloc *upb_arena_alloc(upb_arena *a); +bool upb_arena_addcleanup(upb_arena *a, upb_cleanup_func *func, void *ud); +size_t upb_arena_bytesallocated(const upb_arena *a); +void upb_arena_setnextblocksize(upb_arena *a, size_t size); +void upb_arena_setmaxblocksize(upb_arena *a, size_t size); + +UPB_END_EXTERN_C #ifdef __cplusplus -class upb::ErrorSpace { + +class upb::Arena { + public: + /* A simple arena with no initial memory block and the default allocator. */ + Arena() { upb_arena_init(this); } + + /* Constructs an arena with the given initial block which allocates blocks + * with the given allocator. The given allocator must outlive the Arena. + * + * If you pass NULL for the allocator it will default to the global allocator + * upb_alloc_global, and NULL/0 for the initial block will cause there to be + * no initial block. */ + Arena(void *mem, size_t len, Allocator* a) { + upb_arena_init2(this, mem, len, a); + } + + ~Arena() { upb_arena_uninit(this); } + + /* Sets the size of the next block the Arena will request (unless the + * requested allocation is larger). Each block will double in size until the + * max limit is reached. */ + void SetNextBlockSize(size_t size) { upb_arena_setnextblocksize(this, size); } + + /* Sets the maximum block size. No blocks larger than this will be requested + * from the underlying allocator unless individual arena allocations are + * larger. */ + void SetMaxBlockSize(size_t size) { upb_arena_setmaxblocksize(this, size); } + + /* Allows this arena to be used as a generic allocator. + * + * The arena does not need free() calls so when using Arena as an allocator + * it is safe to skip them. However they are no-ops so there is no harm in + * calling free() either. */ + Allocator* allocator() { return upb_arena_alloc(this); } + + /* Add a cleanup function to run when the arena is destroyed. + * Returns false on out-of-memory. */ + bool AddCleanup(upb_cleanup_func* func, void* ud) { + return upb_arena_addcleanup(this, func, ud); + } + + /* Total number of bytes that have been allocated. It is undefined what + * Realloc() does to this counter. */ + size_t BytesAllocated() const { + return upb_arena_bytesallocated(this); + } + + private: + UPB_DISALLOW_COPY_AND_ASSIGN(Arena) + #else -struct upb_errorspace { -#endif - const char *name; - /* Should the error message in the status object according to this code. */ - void (*set_message)(upb_status* status, int code); +struct upb_arena { +#endif /* __cplusplus */ + /* We implement the allocator interface. + * This must be the first member of upb_arena! */ + upb_alloc alloc; + + /* Allocator to allocate arena blocks. We are responsible for freeing these + * when we are destroyed. */ + upb_alloc *block_alloc; + + size_t bytes_allocated; + size_t next_block_size; + size_t max_block_size; + + /* Linked list of blocks. Points to an arena_block, defined in env.c */ + void *block_head; + + /* Cleanup entries. Pointer to a cleanup_ent, defined in env.c */ + void *cleanup_head; + + /* For future expansion, since the size of this struct is exposed to users. */ + void *future1; + void *future2; }; -#ifdef __cplusplus -/* Object representing a success or failure status. - * It owns no resources and allocates no memory, so it should work - * even in OOM situations. */ +/* upb::Environment ***********************************************************/ -class upb::Status { - public: - Status(); +/* A upb::Environment provides a means for injecting malloc and an + * error-reporting callback into encoders/decoders. This allows them to be + * independent of nearly all assumptions about their actual environment. + * + * It is also a container for allocating the encoders/decoders themselves that + * insulates clients from knowing their actual size. This provides ABI + * compatibility even if the size of the objects change. And this allows the + * structure definitions to be in the .c files instead of the .h files, making + * the .h files smaller and more readable. + * + * We might want to consider renaming this to "Pipeline" if/when the concept of + * a pipeline element becomes more formalized. */ +UPB_DECLARE_TYPE(upb::Environment, upb_env) - /* Returns true if there is no error. */ - bool ok() const; +/* A function that receives an error report from an encoder or decoder. The + * callback can return true to request that the error should be recovered, but + * if the error is not recoverable this has no effect. */ +typedef bool upb_error_func(void *ud, const upb_status *status); - /* Optional error space and code, useful if the caller wants to - * programmatically check the specific kind of error. */ - ErrorSpace* error_space(); - int code() const; +UPB_BEGIN_EXTERN_C - const char *error_message() const; +void upb_env_init(upb_env *e); +void upb_env_uninit(upb_env *e); - /* The error message will be truncated if it is longer than - * UPB_STATUS_MAX_MESSAGE-4. */ - void SetErrorMessage(const char* msg); - void SetFormattedErrorMessage(const char* fmt, ...); +void upb_env_initonly(upb_env *e); - /* If there is no error message already, this will use the ErrorSpace to - * populate the error message for this code. The caller can still call - * SetErrorMessage() to give a more specific message. */ - void SetErrorCode(ErrorSpace* space, int code); +upb_arena *upb_env_arena(upb_env *e); +bool upb_env_ok(const upb_env *e); +void upb_env_seterrorfunc(upb_env *e, upb_error_func *func, void *ud); - /* Resets the status to a successful state with no message. */ - void Clear(); +/* Convenience wrappers around the methods of the contained arena. */ +void upb_env_reporterrorsto(upb_env *e, upb_status *s); +bool upb_env_reporterror(upb_env *e, const upb_status *s); +void *upb_env_malloc(upb_env *e, size_t size); +void *upb_env_realloc(upb_env *e, void *ptr, size_t oldsize, size_t size); +void upb_env_free(upb_env *e, void *ptr); +bool upb_env_addcleanup(upb_env *e, upb_cleanup_func *func, void *ud); +size_t upb_env_bytesallocated(const upb_env *e); + +UPB_END_EXTERN_C + +#ifdef __cplusplus - void CopyFrom(const Status& other); +class upb::Environment { + public: + /* The given Arena must outlive this environment. */ + Environment() { upb_env_initonly(this); } + + Environment(void *mem, size_t len, Allocator *a) : arena_(mem, len, a) { + upb_env_initonly(this); + } + + Arena* arena() { return upb_env_arena(this); } + + /* Set a custom error reporting function. */ + void SetErrorFunction(upb_error_func* func, void* ud) { + upb_env_seterrorfunc(this, func, ud); + } + + /* Set the error reporting function to simply copy the status to the given + * status and abort. */ + void ReportErrorsTo(Status* status) { upb_env_reporterrorsto(this, status); } + + /* Returns true if all allocations and AddCleanup() calls have succeeded, + * and no errors were reported with ReportError() (except ones that recovered + * successfully). */ + bool ok() const { return upb_env_ok(this); } + + /* Reports an error to this environment's callback, returning true if + * the caller should try to recover. */ + bool ReportError(const Status* status) { + return upb_env_reporterror(this, status); + } private: - UPB_DISALLOW_COPY_AND_ASSIGN(Status) + UPB_DISALLOW_COPY_AND_ASSIGN(Environment) + #else -struct upb_status { -#endif +struct upb_env { +#endif /* __cplusplus */ + upb_arena arena_; + upb_error_func *error_func_; + void *error_ud_; bool ok_; +}; - /* Specific status code defined by some error space (optional). */ - int code_; - upb_errorspace *error_space_; - /* Error message; NULL-terminated. */ - char msg[UPB_STATUS_MAX_MESSAGE]; -}; +/* upb::InlinedArena **********************************************************/ +/* upb::InlinedEnvironment ****************************************************/ -#define UPB_STATUS_INIT {true, 0, NULL, {0}} +/* upb::InlinedArena and upb::InlinedEnvironment seed their arenas with a + * predefined amount of memory. No heap memory will be allocated until the + * initial block is exceeded. + * + * These types only exist in C++ */ #ifdef __cplusplus -extern "C" { -#endif -/* The returned string is invalidated by any other call into the status. */ -const char *upb_status_errmsg(const upb_status *status); -bool upb_ok(const upb_status *status); -upb_errorspace *upb_status_errspace(const upb_status *status); -int upb_status_errcode(const upb_status *status); +template <int N> class upb::InlinedArena : public upb::Arena { + public: + InlinedArena() : Arena(initial_block_, N, NULL) {} + explicit InlinedArena(Allocator* a) : Arena(initial_block_, N, a) {} -/* Any of the functions that write to a status object allow status to be NULL, - * to support use cases where the function's caller does not care about the - * status message. */ -void upb_status_clear(upb_status *status); -void upb_status_seterrmsg(upb_status *status, const char *msg); -void upb_status_seterrf(upb_status *status, const char *fmt, ...); -void upb_status_vseterrf(upb_status *status, const char *fmt, va_list args); -void upb_status_seterrcode(upb_status *status, upb_errorspace *space, int code); -void upb_status_copy(upb_status *to, const upb_status *from); + private: + UPB_DISALLOW_COPY_AND_ASSIGN(InlinedArena) -#ifdef __cplusplus -} /* extern "C" */ + char initial_block_[N + UPB_ARENA_BLOCK_OVERHEAD]; +}; -namespace upb { +template <int N> class upb::InlinedEnvironment : public upb::Environment { + public: + InlinedEnvironment() : Environment(initial_block_, N, NULL) {} + explicit InlinedEnvironment(Allocator *a) + : Environment(initial_block_, N, a) {} -/* C++ Wrappers */ -inline Status::Status() { Clear(); } -inline bool Status::ok() const { return upb_ok(this); } -inline const char* Status::error_message() const { - return upb_status_errmsg(this); -} -inline void Status::SetErrorMessage(const char* msg) { - upb_status_seterrmsg(this, msg); -} -inline void Status::SetFormattedErrorMessage(const char* fmt, ...) { - va_list args; - va_start(args, fmt); - upb_status_vseterrf(this, fmt, args); - va_end(args); -} -inline void Status::SetErrorCode(ErrorSpace* space, int code) { - upb_status_seterrcode(this, space, code); -} -inline void Status::Clear() { upb_status_clear(this); } -inline void Status::CopyFrom(const Status& other) { - upb_status_copy(this, &other); -} + private: + UPB_DISALLOW_COPY_AND_ASSIGN(InlinedEnvironment) + + char initial_block_[N + UPB_ARENA_BLOCK_OVERHEAD]; +}; + +#endif /* __cplusplus */ -} /* namespace upb */ -#endif #endif /* UPB_H_ */ |