grpc 1.3.4 → 1.4.0

data/include/grpc/support/alloc.h

@@ -44,26 +44,26 @@ extern "C" {
 
 typedef struct gpr_allocation_functions {
   void *(*malloc_fn)(size_t size);
-  void *(*zalloc_fn)(size_t size); /* if NULL, uses malloc_fn then memset */
+  void *(*zalloc_fn)(size_t size); /** if NULL, uses malloc_fn then memset */
   void *(*realloc_fn)(void *ptr, size_t size);
   void (*free_fn)(void *ptr);
 } gpr_allocation_functions;
 
-/* malloc.
+/** malloc.
  * If size==0, always returns NULL. Otherwise this function never returns NULL.
  * The pointer returned is suitably aligned for any kind of variable it could
  * contain.
  */
 GPRAPI void *gpr_malloc(size_t size);
-/* like malloc, but zero all bytes before returning them */
+/** like malloc, but zero all bytes before returning them */
 GPRAPI void *gpr_zalloc(size_t size);
-/* free */
+/** free */
 GPRAPI void gpr_free(void *ptr);
-/* realloc, never returns NULL */
+/** realloc, never returns NULL */
 GPRAPI void *gpr_realloc(void *p, size_t size);
-/* aligned malloc, never returns NULL, will align to 1 << alignment_log */
+/** aligned malloc, never returns NULL, will align to 1 << alignment_log */
 GPRAPI void *gpr_malloc_aligned(size_t size, size_t alignment_log);
-/* free memory allocated by gpr_malloc_aligned */
+/** free memory allocated by gpr_malloc_aligned */
 GPRAPI void gpr_free_aligned(void *ptr);
 
 /** Request the family of allocation functions in \a functions be used. NOTE

data/include/grpc/support/cmdline.h

@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Simple command line parser.
+/** Simple command line parser.
 
    Supports flags that can be specified as -foo, --foo, --no-foo, -no-foo, etc
    And integers, strings that can be specified as -foo=4, -foo blah, etc
@@ -68,32 +68,32 @@ extern "C" {
 
 typedef struct gpr_cmdline gpr_cmdline;
 
-/* Construct a command line parser: takes a short description of the tool
+/** Construct a command line parser: takes a short description of the tool
    doing the parsing */
 GPRAPI gpr_cmdline *gpr_cmdline_create(const char *description);
-/* Add an integer parameter, with a name (used on the command line) and some
+/** Add an integer parameter, with a name (used on the command line) and some
    helpful text (used in the command usage) */
 GPRAPI void gpr_cmdline_add_int(gpr_cmdline *cl, const char *name,
                                 const char *help, int *value);
-/* The same, for a boolean flag */
+/** The same, for a boolean flag */
 GPRAPI void gpr_cmdline_add_flag(gpr_cmdline *cl, const char *name,
                                  const char *help, int *value);
-/* And for a string */
+/** And for a string */
 GPRAPI void gpr_cmdline_add_string(gpr_cmdline *cl, const char *name,
                                    const char *help, char **value);
-/* Set a callback for non-named arguments */
+/** Set a callback for non-named arguments */
 GPRAPI void gpr_cmdline_on_extra_arg(
     gpr_cmdline *cl, const char *name, const char *help,
     void (*on_extra_arg)(void *user_data, const char *arg), void *user_data);
-/* Enable surviving failure: default behavior is to exit the process */
+/** Enable surviving failure: default behavior is to exit the process */
 GPRAPI void gpr_cmdline_set_survive_failure(gpr_cmdline *cl);
-/* Parse the command line; returns 1 on success, on failure either dies
+/** Parse the command line; returns 1 on success, on failure either dies
    (by default) or returns 0 if gpr_cmdline_set_survive_failure() has been
    called */
 GPRAPI int gpr_cmdline_parse(gpr_cmdline *cl, int argc, char **argv);
-/* Destroy the parser */
+/** Destroy the parser */
 GPRAPI void gpr_cmdline_destroy(gpr_cmdline *cl);
-/* Get a string describing usage */
+/** Get a string describing usage */
 GPRAPI char *gpr_cmdline_usage_string(gpr_cmdline *cl, const char *argv0);
 
 #ifdef __cplusplus

data/include/grpc/support/cpu.h

@@ -40,13 +40,13 @@
 extern "C" {
 #endif
 
-/* Interface providing CPU information for currently running system */
+/** Interface providing CPU information for currently running system */
 
-/* Return the number of CPU cores on the current system. Will return 0 if
+/** Return the number of CPU cores on the current system. Will return 0 if
    the information is not available. */
 GPRAPI unsigned gpr_cpu_num_cores(void);
 
-/* Return the CPU on which the current thread is executing; N.B. This should
+/** Return the CPU on which the current thread is executing; N.B. This should
    be considered advisory only - it is possible that the thread is switched
    to a different CPU at any time. Returns a value in range
    [0, gpr_cpu_num_cores() - 1] */

data/include/grpc/support/histogram.h

@@ -48,7 +48,7 @@ GPRAPI gpr_histogram *gpr_histogram_create(double resolution,
 GPRAPI void gpr_histogram_destroy(gpr_histogram *h);
 GPRAPI void gpr_histogram_add(gpr_histogram *h, double x);
 
-/* The following merges the second histogram into the first. It only works
+/** The following merges the second histogram into the first. It only works
    if they have the same buckets and resolution. Returns 0 on failure, 1
    on success */
 GPRAPI int gpr_histogram_merge(gpr_histogram *dst, const gpr_histogram *src);

data/include/grpc/support/host_port.h

@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Given a host and port, creates a newly-allocated string of the form
+/** Given a host and port, creates a newly-allocated string of the form
    "host:port" or "[ho:st]:port", depending on whether the host contains colons
    like an IPv6 literal.  If the host is already bracketed, then additional
    brackets will not be added.
@@ -52,7 +52,7 @@ extern "C" {
    In the unlikely event of an error, returns -1 and sets *out to NULL. */
 GPRAPI int gpr_join_host_port(char **out, const char *host, int port);
 
-/* Given a name in the form "host:port" or "[ho:st]:port", split into hostname
+/** Given a name in the form "host:port" or "[ho:st]:port", split into hostname
    and port number, into newly allocated strings, which must later be
    destroyed using gpr_free().
    Return 1 on success, 0 on failure. Guarantees *host and *port == NULL on

data/include/grpc/support/log.h

@@ -44,7 +44,7 @@
 extern "C" {
 #endif
 
-/* GPR log API.
+/** GPR log API.
 
    Usage (within grpc):
 
@@ -54,7 +54,7 @@ extern "C" {
    gpr_log(GPR_INFO, "hello world");
    gpr_log(GPR_ERROR, "%d %s!!", argument1, argument2); */
 
-/* The severity of a log message - use the #defines below when calling into
+/** The severity of a log message - use the #defines below when calling into
    gpr_log to additionally supply file and line data */
 typedef enum gpr_log_severity {
   GPR_LOG_SEVERITY_DEBUG,
@@ -64,15 +64,15 @@ typedef enum gpr_log_severity {
 
 #define GPR_LOG_VERBOSITY_UNSET -1
 
-/* Returns a string representation of the log severity */
-const char *gpr_log_severity_string(gpr_log_severity severity);
+/** Returns a string representation of the log severity */
+GPRAPI const char *gpr_log_severity_string(gpr_log_severity severity);
 
-/* Macros to build log contexts at various severity levels */
+/** Macros to build log contexts at various severity levels */
 #define GPR_DEBUG __FILE__, __LINE__, GPR_LOG_SEVERITY_DEBUG
 #define GPR_INFO __FILE__, __LINE__, GPR_LOG_SEVERITY_INFO
 #define GPR_ERROR __FILE__, __LINE__, GPR_LOG_SEVERITY_ERROR
 
-/* Log a message. It's advised to use GPR_xxx above to generate the context
+/** Log a message. It's advised to use GPR_xxx above to generate the context
  * for each message */
 GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity,
                     const char *format, ...) GPR_PRINT_FORMAT_CHECK(4, 5);
@@ -80,12 +80,12 @@ GPRAPI void gpr_log(const char *file, int line, gpr_log_severity severity,
 GPRAPI void gpr_log_message(const char *file, int line,
                             gpr_log_severity severity, const char *message);
 
-/* Set global log verbosity */
+/** Set global log verbosity */
 GPRAPI void gpr_set_log_verbosity(gpr_log_severity min_severity_to_print);
 
 GPRAPI void gpr_log_verbosity_init();
 
-/* Log overrides: applications can use this API to intercept logging calls
+/** Log overrides: applications can use this API to intercept logging calls
    and use their own implementations */
 
 typedef struct {
@@ -98,7 +98,7 @@ typedef struct {
 typedef void (*gpr_log_func)(gpr_log_func_args *args);
 GPRAPI void gpr_set_log_function(gpr_log_func func);
 
-/* abort() the process if x is zero, having written a line to the log.
+/** abort() the process if x is zero, having written a line to the log.
 
    Intended for internal invariants.  If the error can be recovered from,
    without the possibility of corruption, or might best be reflected via

data/include/grpc/support/log_windows.h

@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Returns a string allocated with gpr_malloc that contains a UTF-8
+/** Returns a string allocated with gpr_malloc that contains a UTF-8
  * formatted error message, corresponding to the error messageid.
  * Use in conjunction with GetLastError() et al.
  */

data/include/grpc/support/string_util.h

@@ -40,13 +40,13 @@
 extern "C" {
 #endif
 
-/* String utility functions */
+/** String utility functions */
 
-/* Returns a copy of src that can be passed to gpr_free().
+/** Returns a copy of src that can be passed to gpr_free().
    If allocation fails or if src is NULL, returns NULL. */
 GPRAPI char *gpr_strdup(const char *src);
 
-/* printf to a newly-allocated string.  The set of supported formats may vary
+/** printf to a newly-allocated string.  The set of supported formats may vary
    between platforms.
 
    On success, returns the number of bytes printed (excluding the final '\0'),

data/include/grpc/support/subprocess.h

@@ -42,13 +42,13 @@ extern "C" {
 
 typedef struct gpr_subprocess gpr_subprocess;
 
-/* .exe on windows, empty on unices */
+/** .exe on windows, empty on unices */
 GPRAPI const char *gpr_subprocess_binary_extension();
 
 GPRAPI gpr_subprocess *gpr_subprocess_create(int argc, const char **argv);
-/* if subprocess has not been joined, kill it */
+/** if subprocess has not been joined, kill it */
 GPRAPI void gpr_subprocess_destroy(gpr_subprocess *p);
-/* returns exit status; can be called at most once */
+/** returns exit status; can be called at most once */
 GPRAPI int gpr_subprocess_join(gpr_subprocess *p);
 GPRAPI void gpr_subprocess_interrupt(gpr_subprocess *p);
 

data/include/grpc/support/sync.h

@@ -41,49 +41,49 @@
 extern "C" {
 #endif
 
-/* --- Mutex interface ---
+/** --- Mutex interface ---
 
    At most one thread may hold an exclusive lock on a mutex at any given time.
    Actions taken by a thread that holds a mutex exclusively happen after
    actions taken by all previous holders of the mutex.  Variables of type
    gpr_mu are uninitialized when first declared.  */
 
-/* Initialize *mu.  Requires:  *mu uninitialized.  */
+/** Initialize *mu.  Requires:  *mu uninitialized.  */
 GPRAPI void gpr_mu_init(gpr_mu *mu);
 
-/* Cause *mu no longer to be initialized, freeing any memory in use.  Requires:
+/** Cause *mu no longer to be initialized, freeing any memory in use.  Requires:
    *mu initialized; no other concurrent operation on *mu.  */
 GPRAPI void gpr_mu_destroy(gpr_mu *mu);
 
-/* Wait until no thread has a lock on *mu, cause the calling thread to own an
+/** Wait until no thread has a lock on *mu, cause the calling thread to own an
    exclusive lock on *mu, then return.  May block indefinitely or crash if the
    calling thread has a lock on *mu.  Requires:  *mu initialized.  */
 GPRAPI void gpr_mu_lock(gpr_mu *mu);
 
-/* Release an exclusive lock on *mu held by the calling thread.  Requires:  *mu
+/** Release an exclusive lock on *mu held by the calling thread.  Requires:  *mu
    initialized; the calling thread holds an exclusive lock on *mu.  */
 GPRAPI void gpr_mu_unlock(gpr_mu *mu);
 
-/* Without blocking, attempt to acquire an exclusive lock on *mu for the
+/** Without blocking, attempt to acquire an exclusive lock on *mu for the
    calling thread, then return non-zero iff success.  Fail, if any thread holds
    the lock; succeeds with high probability if no thread holds the lock.
    Requires:  *mu initialized.  */
 GPRAPI int gpr_mu_trylock(gpr_mu *mu);
 
-/* --- Condition variable interface ---
+/** --- Condition variable interface ---
 
    A while-loop should be used with gpr_cv_wait() when waiting for conditions
    to become true.  See the example below.  Variables of type gpr_cv are
    uninitialized when first declared.  */
 
-/* Initialize *cv.  Requires:  *cv uninitialized.  */
+/** Initialize *cv.  Requires:  *cv uninitialized.  */
 GPRAPI void gpr_cv_init(gpr_cv *cv);
 
-/* Cause *cv no longer to be initialized, freeing any memory in use.  Requires:
+/** Cause *cv no longer to be initialized, freeing any memory in use.  Requires:
    *cv initialized; no other concurrent operation on *cv.*/
 GPRAPI void gpr_cv_destroy(gpr_cv *cv);
 
-/* Atomically release *mu and wait on *cv.  When the calling thread is woken
+/** Atomically release *mu and wait on *cv.  When the calling thread is woken
    from *cv or the deadline abs_deadline is exceeded, execute gpr_mu_lock(mu)
    and return whether the deadline was exceeded.  Use
    abs_deadline==gpr_inf_future for no deadline.  abs_deadline can be either
@@ -92,83 +92,83 @@ GPRAPI void gpr_cv_destroy(gpr_cv *cv);
    holds an exclusive lock on *mu.  */
 GPRAPI int gpr_cv_wait(gpr_cv *cv, gpr_mu *mu, gpr_timespec abs_deadline);
 
-/* If any threads are waiting on *cv, wake at least one.
+/** If any threads are waiting on *cv, wake at least one.
    Clients may treat this as an optimization of gpr_cv_broadcast()
    for use in the case where waking more than one waiter is not useful.
    Requires:  *cv initialized.  */
 GPRAPI void gpr_cv_signal(gpr_cv *cv);
 
-/* Wake all threads waiting on *cv.  Requires:  *cv initialized.  */
+/** Wake all threads waiting on *cv.  Requires:  *cv initialized.  */
 GPRAPI void gpr_cv_broadcast(gpr_cv *cv);
 
-/* --- One-time initialization ---
+/** --- One-time initialization ---
 
    gpr_once must be declared with static storage class, and initialized with
    GPR_ONCE_INIT.  e.g.,
      static gpr_once once_var = GPR_ONCE_INIT;     */
 
-/* Ensure that (*init_routine)() has been called exactly once (for the
+/** Ensure that (*init_routine)() has been called exactly once (for the
    specified gpr_once instance) and then return.
    If multiple threads call gpr_once() on the same gpr_once instance, one of
    them will call (*init_routine)(), and the others will block until that call
    finishes.*/
 GPRAPI void gpr_once_init(gpr_once *once, void (*init_routine)(void));
 
-/* --- One-time event notification ---
+/** --- One-time event notification ---
 
   These operations act on a gpr_event, which should be initialized with
   gpr_ev_init(), or with GPR_EVENT_INIT if static, e.g.,
        static gpr_event event_var = GPR_EVENT_INIT;
   It requires no destruction.  */
 
-/* Initialize *ev. */
+/** Initialize *ev. */
 GPRAPI void gpr_event_init(gpr_event *ev);
 
-/* Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
+/** Set *ev so that gpr_event_get() and gpr_event_wait() will return value.
    Requires:  *ev initialized; value != NULL; no prior or concurrent calls to
    gpr_event_set(ev, ...) since initialization.  */
 GPRAPI void gpr_event_set(gpr_event *ev, void *value);
 
-/* Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
+/** Return the value set by gpr_event_set(ev, ...), or NULL if no such call has
    completed.  If the result is non-NULL, all operations that occurred prior to
    the gpr_event_set(ev, ...) set will be visible after this call returns.
    Requires:  *ev initialized.  This operation is faster than acquiring a mutex
    on most platforms.  */
 GPRAPI void *gpr_event_get(gpr_event *ev);
 
-/* Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
+/** Wait until *ev is set by gpr_event_set(ev, ...), or abs_deadline is
    exceeded, then return gpr_event_get(ev).  Requires:  *ev initialized.  Use
    abs_deadline==gpr_inf_future for no deadline.  When the event has been
    signalled before the call, this operation is faster than acquiring a mutex
    on most platforms.  */
 GPRAPI void *gpr_event_wait(gpr_event *ev, gpr_timespec abs_deadline);
 
-/* --- Reference counting ---
+/** --- Reference counting ---
 
    These calls act on the type gpr_refcount.  It requires no destruction.  */
 
-/* Initialize *r to value n.  */
+/** Initialize *r to value n.  */
 GPRAPI void gpr_ref_init(gpr_refcount *r, int n);
 
-/* Increment the reference count *r.  Requires *r initialized. */
+/** Increment the reference count *r.  Requires *r initialized. */
 GPRAPI void gpr_ref(gpr_refcount *r);
 
-/* Increment the reference count *r.  Requires *r initialized.
+/** Increment the reference count *r.  Requires *r initialized.
    Crashes if refcount is zero */
 GPRAPI void gpr_ref_non_zero(gpr_refcount *r);
 
-/* Increment the reference count *r by n.  Requires *r initialized, n > 0. */
+/** Increment the reference count *r by n.  Requires *r initialized, n > 0. */
 GPRAPI void gpr_refn(gpr_refcount *r, int n);
 
-/* Decrement the reference count *r and return non-zero iff it has reached
+/** Decrement the reference count *r and return non-zero iff it has reached
    zero. .  Requires *r initialized. */
 GPRAPI int gpr_unref(gpr_refcount *r);
 
-/* Return non-zero iff the reference count of *r is one, and thus is owned
+/** Return non-zero iff the reference count of *r is one, and thus is owned
    by exactly one object. */
 GPRAPI int gpr_ref_is_unique(gpr_refcount *r);
 
-/* --- Stats counters ---
+/** --- Stats counters ---
 
    These calls act on the integral type gpr_stats_counter.  It requires no
    destruction.  Static instances may be initialized with
@@ -176,16 +176,16 @@ GPRAPI int gpr_ref_is_unique(gpr_refcount *r);
    Beware:  These operations do not imply memory barriers.  Do not use them to
    synchronize other events.  */
 
-/* Initialize *c to the value n. */
+/** Initialize *c to the value n. */
 GPRAPI void gpr_stats_init(gpr_stats_counter *c, intptr_t n);
 
-/* *c += inc.  Requires: *c initialized. */
+/** *c += inc.  Requires: *c initialized. */
 GPRAPI void gpr_stats_inc(gpr_stats_counter *c, intptr_t inc);
 
-/* Return *c.  Requires: *c initialized. */
+/** Return *c.  Requires: *c initialized. */
 GPRAPI intptr_t gpr_stats_read(const gpr_stats_counter *c);
 
-/* ==================Example use of interface===================
+/** ==================Example use of interface===================
    A producer-consumer queue of up to N integers,
    illustrating the use of the calls in this interface. */
 #if 0

data/include/grpc/support/thd.h

@@ -33,7 +33,7 @@
 
 #ifndef GRPC_SUPPORT_THD_H
 #define GRPC_SUPPORT_THD_H
-/* Thread interface for GPR.
+/** Thread interface for GPR.
 
    Types
         gpr_thd_id        a thread identifier.
@@ -50,37 +50,37 @@ extern "C" {
 
 typedef uintptr_t gpr_thd_id;
 
-/* Thread creation options. */
+/** Thread creation options. */
 typedef struct {
-  int flags; /* Opaque field. Get and set with accessors below. */
+  int flags; /** Opaque field. Get and set with accessors below. */
 } gpr_thd_options;
 
-/* Create a new thread running (*thd_body)(arg) and place its thread identifier
+/** Create a new thread running (*thd_body)(arg) and place its thread identifier
    in *t, and return true.  If there are insufficient resources, return false.
    If options==NULL, default options are used.
    The thread is immediately runnable, and exits when (*thd_body)() returns.  */
 GPRAPI int gpr_thd_new(gpr_thd_id *t, void (*thd_body)(void *arg), void *arg,
                        const gpr_thd_options *options);
 
-/* Return a gpr_thd_options struct with all fields set to defaults. */
+/** Return a gpr_thd_options struct with all fields set to defaults. */
 GPRAPI gpr_thd_options gpr_thd_options_default(void);
 
-/* Set the thread to become detached on startup - this is the default. */
+/** Set the thread to become detached on startup - this is the default. */
 GPRAPI void gpr_thd_options_set_detached(gpr_thd_options *options);
 
-/* Set the thread to become joinable - mutually exclusive with detached. */
+/** Set the thread to become joinable - mutually exclusive with detached. */
 GPRAPI void gpr_thd_options_set_joinable(gpr_thd_options *options);
 
-/* Returns non-zero if the option detached is set. */
+/** Returns non-zero if the option detached is set. */
 GPRAPI int gpr_thd_options_is_detached(const gpr_thd_options *options);
 
-/* Returns non-zero if the option joinable is set. */
+/** Returns non-zero if the option joinable is set. */
 GPRAPI int gpr_thd_options_is_joinable(const gpr_thd_options *options);
 
-/* Returns the identifier of the current thread. */
+/** Returns the identifier of the current thread. */
 GPRAPI gpr_thd_id gpr_thd_currentid(void);
 
-/* Blocks until the specified thread properly terminates.
+/** Blocks until the specified thread properly terminates.
    Calling this on a detached thread has unpredictable results. */
 GPRAPI void gpr_thd_join(gpr_thd_id t);