X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_common.h;h=fdcae66fa19e9cc71dd6bc4e1bf89d03b108fa26;hb=17047b7bcbe3f1756028058a9887416c6afab5d8;hp=4552e860e2e3641601d35f48610646cb342347c7;hpb=0c7015a6d8d2b3bf021c216b24d7062cd7375a71;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_common.h b/src/include/gnunet_common.h index 4552e860e..fdcae66fa 100644 --- a/src/include/gnunet_common.h +++ b/src/include/gnunet_common.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2006-2013 Christian Grothoff (and other contributing authors) + Copyright (C) 2006-2013 GNUnet e.V. GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -14,8 +14,8 @@ You should have received a copy of the GNU General Public License along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. */ /** @@ -28,6 +28,8 @@ * @author Nils Durner * * @defgroup logging Logging + * @see [Documentation](https://gnunet.org/logging) + * * @defgroup memory Memory management */ #ifndef GNUNET_COMMON_H @@ -49,6 +51,10 @@ #include #endif +#ifdef HAVE_BYTESWAP_H +#include +#endif + #ifdef __cplusplus extern "C" { @@ -60,13 +66,14 @@ extern "C" /** * Version of the API (for entire gnunetutil.so library). */ -#define GNUNET_UTIL_VERSION 0x00090501 +#define GNUNET_UTIL_VERSION 0x000A0102 + /** - * Named constants for return values. The following - * invariants hold: "GNUNET_NO == 0" (to allow "if (GNUNET_NO)") - * "GNUNET_OK != GNUNET_SYSERR", "GNUNET_OK != GNUNET_NO", "GNUNET_NO != GNUNET_SYSERR" - * and finally "GNUNET_YES != GNUNET_NO". + * Named constants for return values. The following invariants hold: + * `GNUNET_NO == 0` (to allow `if (GNUNET_NO)`) `GNUNET_OK != + * GNUNET_SYSERR`, `GNUNET_OK != GNUNET_NO`, `GNUNET_NO != + * GNUNET_SYSERR` and finally `GNUNET_YES != GNUNET_NO`. */ #define GNUNET_OK 1 #define GNUNET_SYSERR -1 @@ -108,7 +115,7 @@ extern "C" /** * @ingroup logging - * define GNUNET_EXTRA_LOGGING if using this header outside the GNUnet source + * define #GNUNET_EXTRA_LOGGING if using this header outside the GNUnet source * tree where gnunet_config.h is unavailable */ #ifndef GNUNET_EXTRA_LOGGING @@ -217,7 +224,7 @@ extern "C" /** * Define as empty, GNUNET_PACKED should suffice, but this won't work on W32 */ -#define GNUNET_NETWORK_STRUCT_BEGIN +#define GNUNET_NETWORK_STRUCT_BEGIN /** * Define as empty, GNUNET_PACKED should suffice, but this won't work on W32; @@ -250,31 +257,27 @@ struct GNUNET_MessageHeader /** - * @brief A SHA-512 hashcode + * Answer from service to client about last operation. */ -struct GNUNET_HashCode +struct GNUNET_OperationResultMessage { - uint32_t bits[512 / 8 / sizeof (uint32_t)]; /* = 16 */ -}; + struct GNUNET_MessageHeader header; + uint32_t reserved GNUNET_PACKED; -/** - * @brief A SHA-256 hashcode - */ -struct GNUNET_CRYPTO_ShortHashCode -{ - uint32_t bits[256 / 8 / sizeof (uint32_t)]; /* = 8 */ -}; + /** + * Operation ID. + */ + uint64_t op_id GNUNET_PACKED; + /** + * Status code for the operation. + */ + uint64_t result_code GNUNET_PACKED; -/** - * The identity of the host (basically the SHA-512 hashcode of - * it's public key). - */ -struct GNUNET_PeerIdentity -{ - struct GNUNET_HashCode hashPubKey; + /* Followed by data. */ }; + GNUNET_NETWORK_STRUCT_END /** @@ -282,11 +285,39 @@ GNUNET_NETWORK_STRUCT_END * * @param cls closure * @param filename complete filename (absolute path) - * @return GNUNET_OK to continue to iterate, - * GNUNET_NO to stop iteration with no error, - * GNUNET_SYSERR to abort iteration with error! + * @return #GNUNET_OK to continue to iterate, + * #GNUNET_NO to stop iteration with no error, + * #GNUNET_SYSERR to abort iteration with error! */ -typedef int (*GNUNET_FileNameCallback) (void *cls, const char *filename); +typedef int +(*GNUNET_FileNameCallback) (void *cls, + const char *filename); + + +/** + * Generic continuation callback. + * + * @param cls Closure. + */ +typedef void +(*GNUNET_ContinuationCallback) (void *cls); + + +/** + * Function called with the result of an asynchronous operation. + * + * @param cls + * Closure. + * @param result_code + * Result code for the operation. + * @param data + * Data result for the operation. + * @param data_size + * Size of @a data. + */ +typedef void +(*GNUNET_ResultCallback) (void *cls, int64_t result_code, + const void *data, uint16_t data_size); /* ****************************** logging ***************************** */ @@ -301,10 +332,14 @@ enum GNUNET_ErrorType GNUNET_ERROR_TYPE_NONE = 0, GNUNET_ERROR_TYPE_ERROR = 1, GNUNET_ERROR_TYPE_WARNING = 2, - GNUNET_ERROR_TYPE_INFO = 4, - GNUNET_ERROR_TYPE_DEBUG = 8, - GNUNET_ERROR_TYPE_INVALID = 16, - GNUNET_ERROR_TYPE_BULK = 32 + /* UX: We need a message type that is output by + * default without looking like there is a problem. + */ + GNUNET_ERROR_TYPE_MESSAGE = 4, + GNUNET_ERROR_TYPE_INFO = 8, + GNUNET_ERROR_TYPE_DEBUG = 16, + GNUNET_ERROR_TYPE_INVALID = 32, + GNUNET_ERROR_TYPE_BULK = 64 }; @@ -318,9 +353,12 @@ enum GNUNET_ErrorType * @param date when was the message logged? * @param message what is the message */ -typedef void (*GNUNET_Logger) (void *cls, enum GNUNET_ErrorType kind, - const char *component, const char *date, - const char *message); +typedef void +(*GNUNET_Logger) (void *cls, + enum GNUNET_ErrorType kind, + const char *component, + const char *date, + const char *message); /** @@ -330,12 +368,16 @@ typedef void (*GNUNET_Logger) (void *cls, enum GNUNET_ErrorType kind, * @return number of log calls to be ignored */ int -GNUNET_get_log_skip (); +GNUNET_get_log_skip (void); + #if !defined(GNUNET_CULL_LOGGING) int -GNUNET_get_log_call_status (int caller_level, const char *comp, - const char *file, const char *function, int line); +GNUNET_get_log_call_status (int caller_level, + const char *comp, + const char *file, + const char *function, + int line); #endif @@ -348,7 +390,8 @@ GNUNET_get_log_call_status (int caller_level, const char *comp, * @param ... arguments for format string */ void -GNUNET_log_nocheck (enum GNUNET_ErrorType kind, const char *message, ...); +GNUNET_log_nocheck (enum GNUNET_ErrorType kind, const char *message, ...) + __attribute__ ((format (printf, 2, 3))); /* from glib */ #if defined(__GNUC__) && (__GNUC__ > 2) && defined(__OPTIMIZE__) @@ -401,7 +444,7 @@ GNUNET_log_from_nocheck (enum GNUNET_ErrorType kind, const char *comp, }\ } while (0) -#define GNUNET_log(kind,...) do { int log_line = __LINE__;\ + #define GNUNET_log(kind,...) do { int log_line = __LINE__;\ static int log_call_enabled = GNUNET_LOG_CALL_STATUS;\ if ((GNUNET_EXTRA_LOGGING > 0) || ((GNUNET_ERROR_TYPE_DEBUG & (kind)) == 0)) { \ if (GN_UNLIKELY(log_call_enabled == -1))\ @@ -428,7 +471,7 @@ GNUNET_log_from_nocheck (enum GNUNET_ErrorType kind, const char *comp, * @param option name of missing option */ void -GNUNET_log_config_missing (enum GNUNET_ErrorType kind, +GNUNET_log_config_missing (enum GNUNET_ErrorType kind, const char *section, const char *option); @@ -443,7 +486,7 @@ GNUNET_log_config_missing (enum GNUNET_ErrorType kind, * @param required what is required that is invalid about the option */ void -GNUNET_log_config_invalid (enum GNUNET_ErrorType kind, +GNUNET_log_config_invalid (enum GNUNET_ErrorType kind, const char *section, const char *option, const char *required); @@ -452,9 +495,11 @@ GNUNET_log_config_invalid (enum GNUNET_ErrorType kind, /** * @ingroup logging * Abort the process, generate a core dump if possible. + * Most code should use `GNUNET_assert (0)` instead to + * first log the location of the failure. */ void -GNUNET_abort (void) GNUNET_NORETURN; +GNUNET_abort_ (void) GNUNET_NORETURN; /** @@ -462,10 +507,11 @@ GNUNET_abort (void) GNUNET_NORETURN; * Ignore the next @a n calls to the log function. * * @param n number of log calls to ignore (could be negative) - * @param check_reset GNUNET_YES to assert that the log skip counter is currently zero + * @param check_reset #GNUNET_YES to assert that the log skip counter is currently zero */ void -GNUNET_log_skip (int n, int check_reset); +GNUNET_log_skip (int n, + int check_reset); /** @@ -475,21 +521,27 @@ GNUNET_log_skip (int n, int check_reset); * @param comp default component to use * @param loglevel what types of messages should be logged * @param logfile change logging to logfile (use NULL to keep stderr) - * @return GNUNET_OK on success, GNUNET_SYSERR if logfile could not be opened + * @return #GNUNET_OK on success, #GNUNET_SYSERR if logfile could not be opened */ int -GNUNET_log_setup (const char *comp, const char *loglevel, const char *logfile); +GNUNET_log_setup (const char *comp, + const char *loglevel, + const char *logfile); /** * @ingroup logging - * Add a custom logger. + * Add a custom logger. Note that installing any custom logger + * will disable the standard logger. When multiple custom loggers + * are installed, all will be called. The standard logger will + * only be used if no custom loggers are present. * * @param logger log function - * @param logger_cls closure for logger + * @param logger_cls closure for @a logger */ void -GNUNET_logger_add (GNUNET_Logger logger, void *logger_cls); +GNUNET_logger_add (GNUNET_Logger logger, + void *logger_cls); /** @@ -497,10 +549,11 @@ GNUNET_logger_add (GNUNET_Logger logger, void *logger_cls); * Remove a custom logger. * * @param logger log function - * @param logger_cls closure for logger + * @param logger_cls closure for @a logger */ void -GNUNET_logger_remove (GNUNET_Logger logger, void *logger_cls); +GNUNET_logger_remove (GNUNET_Logger logger, + void *logger_cls); /** @@ -509,30 +562,30 @@ GNUNET_logger_remove (GNUNET_Logger logger, void *logger_cls); * This is one of the very few calls in the entire API that is * NOT reentrant! * - * @param hc the short hash code + * @param shc the hash code * @return string */ const char * -GNUNET_short_h2s (const struct GNUNET_CRYPTO_ShortHashCode * hc); +GNUNET_sh2s (const struct GNUNET_ShortHashCode *shc); /** * @ingroup logging - * Convert a short hash value to a string (for printing debug messages). - * This prints all 104 characters of a hashcode! + * Convert a hash value to a string (for printing debug messages). * This is one of the very few calls in the entire API that is * NOT reentrant! * - * @param hc the short hash code + * @param hc the hash code * @return string */ const char * -GNUNET_short_h2s_full (const struct GNUNET_CRYPTO_ShortHashCode * hc); +GNUNET_h2s (const struct GNUNET_HashCode * hc); /** * @ingroup logging * Convert a hash value to a string (for printing debug messages). + * This prints all 104 characters of a hashcode! * This is one of the very few calls in the entire API that is * NOT reentrant! * @@ -540,35 +593,37 @@ GNUNET_short_h2s_full (const struct GNUNET_CRYPTO_ShortHashCode * hc); * @return string */ const char * -GNUNET_h2s (const struct GNUNET_HashCode * hc); +GNUNET_h2s_full (const struct GNUNET_HashCode * hc); /** * @ingroup logging - * Convert a hash value to a string (for printing debug messages). - * This prints all 104 characters of a hashcode! + * Convert a peer identity to a string (for printing debug messages). * This is one of the very few calls in the entire API that is * NOT reentrant! * - * @param hc the hash code - * @return string + * @param pid the peer identity + * @return string form of the pid; will be overwritten by next + * call to #GNUNET_i2s(). */ const char * -GNUNET_h2s_full (const struct GNUNET_HashCode * hc); +GNUNET_i2s (const struct GNUNET_PeerIdentity *pid); /** * @ingroup logging * Convert a peer identity to a string (for printing debug messages). * This is one of the very few calls in the entire API that is - * NOT reentrant! + * NOT reentrant! Identical to #GNUNET_i2s(), except that another + * buffer is used so both #GNUNET_i2s() and #GNUNET_i2s2() can be + * used within the same log statement. * * @param pid the peer identity * @return string form of the pid; will be overwritten by next - * call to GNUNET_i2s. + * call to #GNUNET_i2s(). */ const char * -GNUNET_i2s (const struct GNUNET_PeerIdentity *pid); +GNUNET_i2s2 (const struct GNUNET_PeerIdentity *pid); /** @@ -579,7 +634,7 @@ GNUNET_i2s (const struct GNUNET_PeerIdentity *pid); * * @param pid the peer identity * @return string form of the pid; will be overwritten by next - * call to GNUNET_i2s. + * call to #GNUNET_i2s_full(). */ const char * GNUNET_i2s_full (const struct GNUNET_PeerIdentity *pid); @@ -592,12 +647,13 @@ GNUNET_i2s_full (const struct GNUNET_PeerIdentity *pid); * in the entire API that is NOT reentrant! * * @param addr the address - * @param addrlen the length of the address + * @param addrlen the length of the @a addr * @return nicely formatted string for the address - * will be overwritten by next call to GNUNET_a2s. + * will be overwritten by next call to #GNUNET_a2s(). */ const char * -GNUNET_a2s (const struct sockaddr *addr, socklen_t addrlen); +GNUNET_a2s (const struct sockaddr *addr, + socklen_t addrlen); /** @@ -615,14 +671,24 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind); * @ingroup logging * Use this for fatal errors that cannot be handled */ -#define GNUNET_assert(cond) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort(); } } while(0) +#define GNUNET_assert(cond) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort_(); } } while(0) /** * @ingroup logging * Use this for fatal errors that cannot be handled */ -#define GNUNET_assert_at(cond, f, l) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), f, l); GNUNET_abort(); } } while(0) +#define GNUNET_assert_at(cond, f, l) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), f, l); GNUNET_abort_(); } } while(0) + + +/** + * @ingroup logging + * Use this for fatal errors that cannot be handled + * + * @param cond Condition to evaluate + * @param comp Component string to use for logging + */ +#define GNUNET_assert_from(cond, comp) do { if (! (cond)) { GNUNET_log_from(GNUNET_ERROR_TYPE_ERROR, comp, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); GNUNET_abort_(); } } while(0) /** @@ -669,7 +735,7 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind); * a failure of the command 'cmd' with the message given * by strerror(errno). */ -#define GNUNET_log_strerror_file(level, cmd, filename) do { GNUNET_log(level, _("`%s' failed on file `%s' at %s:%d with error: %s\n"), cmd, filename,__FILE__, __LINE__, STRERROR(errno)); } while(0) +#define GNUNET_log_strerror_file(level, cmd, filename) do { GNUNET_log(level, _("`%s' failed on file `%s' at %s:%d with error: %s\n"), cmd, filename, __FILE__, __LINE__, STRERROR(errno)); } while(0) /** @@ -683,37 +749,53 @@ GNUNET_error_type_to_string (enum GNUNET_ErrorType kind); /* ************************* endianess conversion ****************** */ /** - * Convert unsigned 64-bit integer to host-byte-order. - * @param n the value in network byte order - * @return the same value in host byte order + * Convert unsigned 64-bit integer to network byte order. + * + * @param n + * The value in host byte order. + * + * @return The same value in network byte order. */ uint64_t -GNUNET_ntohll (uint64_t n); +GNUNET_htonll (uint64_t n); + /** - * Convert unsigned 64-bit integer to network-byte-order. - * @param n the value in host byte order - * @return the same value in network byte order + * Convert unsigned 64-bit integer to host byte order. + * + * @param n + * The value in network byte order. + * + * @return The same value in host byte order. */ uint64_t -GNUNET_htonll (uint64_t n); +GNUNET_ntohll (uint64_t n); + /** - * Convert double to network-byte-order. - * @param d the value in network byte order - * @return the same value in host byte order + * Convert double to network byte order. + * + * @param d + * The value in host byte order. + * + * @return The same value in network byte order. */ -double +double GNUNET_hton_double (double d); + /** - * Convert double to host-byte-order - * @param d the value in network byte order - * @return the same value in host byte order + * Convert double to host byte order + * + * @param d + * The value in network byte order. + * + * @return The same value in host byte order. */ -double +double GNUNET_ntoh_double (double d); + /* ************************* allocation functions ****************** */ /** @@ -724,14 +806,60 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory - * Allocate a struct or union of the given 'type'. - * Wrapper around GNUNET_malloc that returns a pointer + * Allocate a struct or union of the given @a type. + * Wrapper around #GNUNET_malloc that returns a pointer * to the newly created object of the correct type. * * @param type name of the struct or union, i.e. pass 'struct Foo'. */ #define GNUNET_new(type) (type *) GNUNET_malloc (sizeof (type)) +/** + * Call memcpy() but check for @a n being 0 first. In the latter + * case, it is now safe to pass NULL for @a src or @a dst. + * Unlike traditional memcpy(), returns nothing. + * + * @param dst destination of the copy, may be NULL if @a n is zero + * @param src source of the copy, may be NULL if @a n is zero + * @param n number of bytes to copy + */ +#define GNUNET_memcpy(dst,src,n) do { if (0 != n) { (void) memcpy (dst,src,n); } } while (0) + + +/** + * @ingroup memory + * Allocate a size @a n array with structs or unions of the given @a type. + * Wrapper around #GNUNET_malloc that returns a pointer + * to the newly created objects of the correct type. + * + * @param n number of elements in the array + * @param type name of the struct or union, i.e. pass 'struct Foo'. + */ +#define GNUNET_new_array(n, type) (type *) GNUNET_malloc ((n) * sizeof (type)) + +/** + * @ingroup memory + * Allocate a size @a n times @a m array + * with structs or unions of the given @a type. + * + * @param n size of the first dimension + * @param m size of the second dimension + * @param type name of the struct or union, i.e. pass 'struct Foo'. + */ +#define GNUNET_new_array_2d(n, m, type) (type **) GNUNET_xnew_array_2d_ (n, m, sizeof (type), __FILE__, __LINE__) + +/** + * @ingroup memory + * Allocate a size @a n times @a m times @a o array + * with structs or unions of the given @a type. + * + * @param n size of the first dimension + * @param m size of the second dimension + * @param o size of the third dimension + * @param type name of the struct or union, i.e. pass 'struct Foo'. + */ +#define GNUNET_new_array_3d(n, m, o, type) (type ***) GNUNET_xnew_array_3d_ (n, m, o, sizeof (type), __FILE__, __LINE__) + /** * @ingroup memory * Wrapper around malloc. Allocates size bytes of memory. @@ -765,7 +893,8 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory - * Wrapper around realloc. Rellocates size bytes of memory. + * Wrapper around realloc. Reallocates size bytes of memory. + * The content of the intersection of the new and old size will be unchanged. * * @param ptr the pointer to reallocate * @param size the number of bytes to reallocate @@ -776,18 +905,18 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory * Wrapper around free. Frees the memory referred to by ptr. - * Note that is is generally better to free memory that was - * allocated with GNUNET_array_grow using GNUNET_array_grow(mem, size, 0) instead of GNUNET_free. + * Note that it is generally better to free memory that was + * allocated with #GNUNET_array_grow using #GNUNET_array_grow(mem, size, 0) instead of #GNUNET_free. * * @param ptr location where to free the memory. ptr must have - * been returned by GNUNET_strdup, GNUNET_strndup, GNUNET_malloc or GNUNET_array_grow earlier. + * been returned by #GNUNET_strdup, #GNUNET_strndup, #GNUNET_malloc or #GNUNET_array_grow earlier. */ #define GNUNET_free(ptr) GNUNET_xfree_(ptr, __FILE__, __LINE__) /** * @ingroup memory * Free the memory pointed to by ptr if ptr is not NULL. - * Equivalent to if (ptr!=null)GNUNET_free(ptr). + * Equivalent to `if (NULL != ptr) GNUNET_free(ptr)`. * * @param ptr the location in memory to free */ @@ -795,7 +924,7 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory - * Wrapper around GNUNET_strdup. Makes a copy of the zero-terminated string + * Wrapper around #GNUNET_xstrdup_. Makes a copy of the zero-terminated string * pointed to by a. * * @param a pointer to a zero-terminated string @@ -805,7 +934,7 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory - * Wrapper around GNUNET_strndup. Makes a partial copy of the string + * Wrapper around #GNUNET_xstrndup_. Makes a partial copy of the string * pointed to by a. * * @param a pointer to a string @@ -817,8 +946,8 @@ GNUNET_ntoh_double (double d); /** * @ingroup memory * Grow a well-typed (!) array. This is a convenience - * method to grow a vector arr of size size - * to the new (target) size tsize. + * method to grow a vector @a arr of size @a size + * to the new (target) size @a tsize. *

* * Example (simple, well-typed stack): @@ -829,12 +958,12 @@ GNUNET_ntoh_double (double d); * * static void push(struct foo * elem) { * GNUNET_array_grow(myVector, myVecLen, myVecLen+1); - * memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo)); + * GNUNET_memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo)); * } * * static void pop(struct foo * elem) { * if (myVecLen == 0) die(); - * memcpy(elem, myVector[myVecLen-1], sizeof(struct foo)); + * GNUNET_memcpy(elem, myVector[myVecLen-1], sizeof(struct foo)); * GNUNET_array_grow(myVector, myVecLen, myVecLen-1); * } * @@ -862,7 +991,7 @@ GNUNET_ntoh_double (double d); * Like snprintf, just aborts if the buffer is of insufficient size. * * @param buf pointer to buffer that is written to - * @param size number of bytes in buf + * @param size number of bytes in @a buf * @param format format strings * @param ... data for format string * @return number of bytes written to buf or negative value on error @@ -889,7 +1018,7 @@ GNUNET_asprintf (char **buf, const char *format, ...); /** * Allocate memory. Checks the return value, aborts if no more * memory is available. Don't use GNUNET_xmalloc_ directly. Use the - * GNUNET_malloc macro. + * #GNUNET_malloc macro. * The memory will be zero'ed out. * * @param size number of bytes to allocate @@ -901,10 +1030,49 @@ void * GNUNET_xmalloc_ (size_t size, const char *filename, int linenumber); +/** + * Allocate memory for a two dimensional array in one block + * and set up pointers. Aborts if no more memory is available. + * Don't use GNUNET_xnew_array_2d_ directly. Use the + * #GNUNET_new_array_2d macro. + * The memory of the elements will be zero'ed out. + * + * @param n size of the first dimension + * @param m size of the second dimension + * @param elementSize size of a single element in bytes + * @param filename where is this call being made (for debugging) + * @param linenumber line where this call is being made (for debugging) + * @return allocated memory, never NULL + */ +void ** +GNUNET_xnew_array_2d_ (size_t n, size_t m, size_t elementSize, + const char *filename, int linenumber); + + +/** + * Allocate memory for a three dimensional array in one block + * and set up pointers. Aborts if no more memory is available. + * Don't use GNUNET_xnew_array_3d_ directly. Use the + * #GNUNET_new_array_3d macro. + * The memory of the elements will be zero'ed out. + * + * @param n size of the first dimension + * @param m size of the second dimension + * @param o size of the third dimension + * @param elementSize size of a single element in bytes + * @param filename where is this call being made (for debugging) + * @param linenumber line where this call is being made (for debugging) + * @return allocated memory, never NULL + */ +void *** +GNUNET_xnew_array_3d_ (size_t n, size_t m, size_t o, size_t elementSize, + const char *filename, int linenumber); + + /** * Allocate and initialize memory. Checks the return value, aborts if no more * memory is available. Don't use GNUNET_xmemdup_ directly. Use the - * GNUNET_memdup macro. + * #GNUNET_memdup macro. * * @param buf buffer to initialize from (must contain size bytes) * @param size number of bytes to allocate @@ -921,7 +1089,7 @@ GNUNET_xmemdup_ (const void *buf, size_t size, const char *filename, * Allocate memory. This function does not check if the allocation * request is within reasonable bounds, allowing allocations larger * than 40 MB. If you don't expect the possibility of very large - * allocations, use GNUNET_malloc instead. The memory will be zero'ed + * allocations, use #GNUNET_malloc instead. The memory will be zero'ed * out. * * @param size number of bytes to allocate @@ -932,6 +1100,7 @@ GNUNET_xmemdup_ (const void *buf, size_t size, const char *filename, void * GNUNET_xmalloc_unchecked_ (size_t size, const char *filename, int linenumber); + /** * Reallocate memory. Checks the return value, aborts if no more * memory is available. @@ -939,10 +1108,11 @@ GNUNET_xmalloc_unchecked_ (size_t size, const char *filename, int linenumber); void * GNUNET_xrealloc_ (void *ptr, size_t n, const char *filename, int linenumber); + /** * Free memory. Merely a wrapper for the case that we * want to keep track of allocations. Don't use GNUNET_xfree_ - * directly. Use the GNUNET_free macro. + * directly. Use the #GNUNET_free macro. * * @param ptr pointer to memory to free * @param filename where is this call being made (for debugging) @@ -953,7 +1123,7 @@ GNUNET_xfree_ (void *ptr, const char *filename, int linenumber); /** - * Dup a string. Don't call GNUNET_xstrdup_ directly. Use the GNUNET_strdup macro. + * Dup a string. Don't call GNUNET_xstrdup_ directly. Use the #GNUNET_strdup macro. * @param str string to duplicate * @param filename where is this call being made (for debugging) * @param linenumber line where this call is being made (for debugging) @@ -963,7 +1133,7 @@ char * GNUNET_xstrdup_ (const char *str, const char *filename, int linenumber); /** - * Dup partially a string. Don't call GNUNET_xstrndup_ directly. Use the GNUNET_strndup macro. + * Dup partially a string. Don't call GNUNET_xstrndup_ directly. Use the #GNUNET_strndup macro. * * @param str string to duplicate * @param len length of the string to duplicate @@ -980,7 +1150,7 @@ GNUNET_xstrndup_ (const char *str, size_t len, const char *filename, * Grows old by (*oldCount-newCount)*elementSize * bytes and sets *oldCount to newCount. * - * Don't call GNUNET_xgrow_ directly. Use the GNUNET_array_grow macro. + * Don't call GNUNET_xgrow_ directly. Use the #GNUNET_array_grow macro. * * @param old address of the pointer to the array * *old may be NULL @@ -1015,6 +1185,75 @@ GNUNET_copy_message (const struct GNUNET_MessageHeader *msg); #endif +/** + * Valid task priorities. Use these, do not pass random integers! + * For various reasons (#3862 -- building with QT Creator, and + * our restricted cross-compilation with emscripten) this cannot + * be in gnunet_scheduler_lib.h, but it works if we declare it here. + * Naturally, logically this is part of the scheduler. + */ +enum GNUNET_SCHEDULER_Priority +{ + /** + * Run with the same priority as the current job. + */ + GNUNET_SCHEDULER_PRIORITY_KEEP = 0, + + /** + * Run when otherwise idle. + */ + GNUNET_SCHEDULER_PRIORITY_IDLE = 1, + + /** + * Run as background job (higher than idle, + * lower than default). + */ + GNUNET_SCHEDULER_PRIORITY_BACKGROUND = 2, + + /** + * Run with the default priority (normal + * P2P operations). Any task that is scheduled + * without an explicit priority being specified + * will run with this priority. + */ + GNUNET_SCHEDULER_PRIORITY_DEFAULT = 3, + + /** + * Run with high priority (important requests). + * Higher than DEFAULT. + */ + GNUNET_SCHEDULER_PRIORITY_HIGH = 4, + + /** + * Run with priority for interactive tasks. + * Higher than "HIGH". + */ + GNUNET_SCHEDULER_PRIORITY_UI = 5, + + /** + * Run with priority for urgent tasks. Use + * for things like aborts and shutdowns that + * need to preempt "UI"-level tasks. + * Higher than "UI". + */ + GNUNET_SCHEDULER_PRIORITY_URGENT = 6, + + /** + * This is an internal priority level that is only used for tasks + * that are being triggered due to shutdown (they have automatically + * highest priority). User code must not use this priority level + * directly. Tasks run with this priority level that internally + * schedule other tasks will see their original priority level + * be inherited (unless otherwise specified). + */ + GNUNET_SCHEDULER_PRIORITY_SHUTDOWN = 7, + + /** + * Number of priorities (must be the last priority). + * This priority must not be used by clients. + */ + GNUNET_SCHEDULER_PRIORITY_COUNT = 8 +}; #if 0 /* keep Emacsens' auto-indent happy */ @@ -1024,7 +1263,4 @@ GNUNET_copy_message (const struct GNUNET_MessageHeader *msg); } #endif - - - -#endif /*GNUNET_COMMON_H_ */ +#endif /* GNUNET_COMMON_H */