diff options
author | 2017-05-03 14:49:41 -0700 | |
---|---|---|
committer | 2017-05-05 11:02:07 -0700 | |
commit | d809a15ec4913c7a8cd38d679a78b3edcb716b69 (patch) | |
tree | 32a3f1cfe4604c1c1003f25a6bbdfd95314e82aa /include/grpc/support | |
parent | 3f716baa0a33529592c6cfeb64950fe463c4595f (diff) |
cpp doc nits
Diffstat (limited to 'include/grpc/support')
-rw-r--r-- | include/grpc/support/alloc.h | 14 | ||||
-rw-r--r-- | include/grpc/support/cmdline.h | 20 | ||||
-rw-r--r-- | include/grpc/support/cpu.h | 6 | ||||
-rw-r--r-- | include/grpc/support/histogram.h | 2 | ||||
-rw-r--r-- | include/grpc/support/host_port.h | 4 | ||||
-rw-r--r-- | include/grpc/support/log.h | 16 | ||||
-rw-r--r-- | include/grpc/support/log_windows.h | 2 | ||||
-rw-r--r-- | include/grpc/support/string_util.h | 6 | ||||
-rw-r--r-- | include/grpc/support/subprocess.h | 6 | ||||
-rw-r--r-- | include/grpc/support/sync.h | 62 | ||||
-rw-r--r-- | include/grpc/support/thd.h | 22 | ||||
-rw-r--r-- | include/grpc/support/time.h | 24 | ||||
-rw-r--r-- | include/grpc/support/tls.h | 2 | ||||
-rw-r--r-- | include/grpc/support/tls_gcc.h | 4 | ||||
-rw-r--r-- | include/grpc/support/tls_msvc.h | 2 | ||||
-rw-r--r-- | include/grpc/support/tls_pthread.h | 2 | ||||
-rw-r--r-- | include/grpc/support/useful.h | 4 |
17 files changed, 99 insertions, 99 deletions
diff --git a/include/grpc/support/alloc.h b/include/grpc/support/alloc.h index 017d75a3d0..99be2d161a 100644 --- a/include/grpc/support/alloc.h +++ b/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 diff --git a/include/grpc/support/cmdline.h b/include/grpc/support/cmdline.h index 5b7bc82594..5a83afb464 100644 --- a/include/grpc/support/cmdline.h +++ b/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 diff --git a/include/grpc/support/cpu.h b/include/grpc/support/cpu.h index 6734feb391..0da02ada22 100644 --- a/include/grpc/support/cpu.h +++ b/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] */ diff --git a/include/grpc/support/histogram.h b/include/grpc/support/histogram.h index c545038528..96db758878 100644 --- a/include/grpc/support/histogram.h +++ b/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); diff --git a/include/grpc/support/host_port.h b/include/grpc/support/host_port.h index 15819543a9..ee786beb19 100644 --- a/include/grpc/support/host_port.h +++ b/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 diff --git a/include/grpc/support/log.h b/include/grpc/support/log.h index 88346cc9f4..917b01183a 100644 --- a/include/grpc/support/log.h +++ b/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 */ +/** Returns a string representation of the log severity */ 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 diff --git a/include/grpc/support/log_windows.h b/include/grpc/support/log_windows.h index 943a8e908b..b8a4078464 100644 --- a/include/grpc/support/log_windows.h +++ b/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. */ diff --git a/include/grpc/support/string_util.h b/include/grpc/support/string_util.h index 5ab983d15d..8b268a6006 100644 --- a/include/grpc/support/string_util.h +++ b/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'), diff --git a/include/grpc/support/subprocess.h b/include/grpc/support/subprocess.h index 2baa43ece2..dfb80989dc 100644 --- a/include/grpc/support/subprocess.h +++ b/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); diff --git a/include/grpc/support/sync.h b/include/grpc/support/sync.h index 5cfeecb601..7d727a0cfc 100644 --- a/include/grpc/support/sync.h +++ b/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 diff --git a/include/grpc/support/thd.h b/include/grpc/support/thd.h index 0514288793..ba6cbb0cb0 100644 --- a/include/grpc/support/thd.h +++ b/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); diff --git a/include/grpc/support/time.h b/include/grpc/support/time.h index 66bcfca6ed..2384f5e906 100644 --- a/include/grpc/support/time.h +++ b/include/grpc/support/time.h @@ -43,11 +43,11 @@ extern "C" { #endif -/* Time constants. */ +/** Time constants. */ GPRAPI gpr_timespec -gpr_time_0(gpr_clock_type type); /* The zero time interval. */ -GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /* The far future */ -GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ +gpr_time_0(gpr_clock_type type); /** The zero time interval. */ +GPRAPI gpr_timespec gpr_inf_future(gpr_clock_type type); /** The far future */ +GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /** The far past. */ #define GPR_MS_PER_SEC 1000 #define GPR_US_PER_SEC 1000000 @@ -56,28 +56,28 @@ GPRAPI gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ #define GPR_NS_PER_US 1000 #define GPR_US_PER_MS 1000 -/* initialize time subsystem */ +/** initialize time subsystem */ GPRAPI void gpr_time_init(void); -/* Return the current time measured from the given clocks epoch. */ +/** Return the current time measured from the given clocks epoch. */ GPRAPI gpr_timespec gpr_now(gpr_clock_type clock); -/* Convert a timespec from one clock to another */ +/** Convert a timespec from one clock to another */ GPRAPI gpr_timespec gpr_convert_clock_type(gpr_timespec t, gpr_clock_type target_clock); -/* Return -ve, 0, or +ve according to whether a < b, a == b, or a > b +/** Return -ve, 0, or +ve according to whether a < b, a == b, or a > b respectively. */ GPRAPI int gpr_time_cmp(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_max(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_min(gpr_timespec a, gpr_timespec b); -/* Add and subtract times. Calculations saturate at infinities. */ +/** Add and subtract times. Calculations saturate at infinities. */ GPRAPI gpr_timespec gpr_time_add(gpr_timespec a, gpr_timespec b); GPRAPI gpr_timespec gpr_time_sub(gpr_timespec a, gpr_timespec b); -/* Return a timespec representing a given number of time units. INT64_MIN is +/** Return a timespec representing a given number of time units. INT64_MIN is interpreted as gpr_inf_past, and INT64_MAX as gpr_inf_future. */ GPRAPI gpr_timespec gpr_time_from_micros(int64_t x, gpr_clock_type clock_type); GPRAPI gpr_timespec gpr_time_from_nanos(int64_t x, gpr_clock_type clock_type); @@ -88,12 +88,12 @@ GPRAPI gpr_timespec gpr_time_from_hours(int64_t x, gpr_clock_type clock_type); GPRAPI int32_t gpr_time_to_millis(gpr_timespec timespec); -/* Return 1 if two times are equal or within threshold of each other, +/** Return 1 if two times are equal or within threshold of each other, 0 otherwise */ GPRAPI int gpr_time_similar(gpr_timespec a, gpr_timespec b, gpr_timespec threshold); -/* Sleep until at least 'until' - an absolute timeout */ +/** Sleep until at least 'until' - an absolute timeout */ GPRAPI void gpr_sleep_until(gpr_timespec until); GPRAPI double gpr_timespec_to_micros(gpr_timespec t); diff --git a/include/grpc/support/tls.h b/include/grpc/support/tls.h index 5365449f0d..a48c73b26f 100644 --- a/include/grpc/support/tls.h +++ b/include/grpc/support/tls.h @@ -36,7 +36,7 @@ #include <grpc/support/port_platform.h> -/* Thread local storage. +/** Thread local storage. A minimal wrapper that should be implementable across many compilers, and implementable efficiently across most modern compilers. diff --git a/include/grpc/support/tls_gcc.h b/include/grpc/support/tls_gcc.h index a47275f6f4..9667524d34 100644 --- a/include/grpc/support/tls_gcc.h +++ b/include/grpc/support/tls_gcc.h @@ -38,7 +38,7 @@ #include <grpc/support/log.h> -/* Thread local storage based on gcc compiler primitives. +/** Thread local storage based on gcc compiler primitives. #include tls.h to use this - and see that file for documentation */ #ifndef NDEBUG @@ -58,7 +58,7 @@ struct gpr_gcc_thread_local { *((tls)->inited) = true; \ } while (0) -/* It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */ +/** It is allowed to call gpr_tls_init after gpr_tls_destroy is called. */ #define gpr_tls_destroy(tls) \ do { \ GPR_ASSERT(*((tls)->inited)); \ diff --git a/include/grpc/support/tls_msvc.h b/include/grpc/support/tls_msvc.h index efc653b4e4..4ef8eeff0d 100644 --- a/include/grpc/support/tls_msvc.h +++ b/include/grpc/support/tls_msvc.h @@ -34,7 +34,7 @@ #ifndef GRPC_SUPPORT_TLS_MSVC_H #define GRPC_SUPPORT_TLS_MSVC_H -/* Thread local storage based on ms visual c compiler primitives. +/** Thread local storage based on ms visual c compiler primitives. #include tls.h to use this - and see that file for documentation */ struct gpr_msvc_thread_local { diff --git a/include/grpc/support/tls_pthread.h b/include/grpc/support/tls_pthread.h index e681da2ecd..7cc6a40645 100644 --- a/include/grpc/support/tls_pthread.h +++ b/include/grpc/support/tls_pthread.h @@ -37,7 +37,7 @@ #include <grpc/support/log.h> /* for GPR_ASSERT */ #include <pthread.h> -/* Thread local storage based on pthread library calls. +/** Thread local storage based on pthread library calls. #include tls.h to use this - and see that file for documentation */ struct gpr_pthread_thread_local { diff --git a/include/grpc/support/useful.h b/include/grpc/support/useful.h index 9d8314e4be..c261fbaa14 100644 --- a/include/grpc/support/useful.h +++ b/include/grpc/support/useful.h @@ -34,12 +34,12 @@ #ifndef GRPC_SUPPORT_USEFUL_H #define GRPC_SUPPORT_USEFUL_H -/* useful macros that don't belong anywhere else */ +/** useful macros that don't belong anywhere else */ #define GPR_MIN(a, b) ((a) < (b) ? (a) : (b)) #define GPR_MAX(a, b) ((a) > (b) ? (a) : (b)) #define GPR_CLAMP(a, min, max) ((a) < (min) ? (min) : (a) > (max) ? (max) : (a)) -/* rotl, rotr assume x is unsigned */ +/** rotl, rotr assume x is unsigned */ #define GPR_ROTL(x, n) (((x) << (n)) | ((x) >> (sizeof(x) * 8 - (n)))) #define GPR_ROTR(x, n) (((x) >> (n)) | ((x) << (sizeof(x) * 8 - (n)))) |