-/* Placed into the public domain */
+/* CC0 (Public domain) - see LICENSE file for details */
#ifndef CCAN_TCON_H
#define CCAN_TCON_H
#include "config.h"
*
* This declares a _tcon member for a structure. It should be the
* last element in your structure; with sufficient compiler support it
- * will not use any actual storage. tcon_to_raw() will compare
+ * will not use any actual storage. tcon_check() will compare
* expressions with one of these "type canaries" to cause warnings if
* the container is misused.
*
- * A type of "void *" will allow tcon_to_raw() to pass on any (pointer) type.
+ * A type of "void *" will allow tcon_check() to pass on any (pointer) type.
*
* Example:
* // Simply typesafe linked list.
#define TCON(decls) struct { decls; } _tcon[1]
#endif
+/**
+ * TCON_WRAP - declare a wrapper type containing a base type and type canaries
+ * @basetype: the base type to wrap
+ * @decls: the semi-colon separated list of type canaries.
+ *
+ * This expands to a new type which includes the given base type, and
+ * also type canaries, similar to those created with TCON.
+ *
+ * The embedded base type value can be accessed using tcon_unwrap().
+ *
+ * Differences from using TCON()
+ * - The wrapper type will take either the size of the base type, or
+ * the size of a single pointer, whichever is greater (regardless of
+ * compiler)
+ * - A TCON_WRAP type may be included in another structure, and need
+ * not be the last element.
+ *
+ * A type of "void *" will allow tcon_check() to pass on any (pointer) type.
+ *
+ * Example:
+ * // Simply typesafe linked list.
+ * struct list_head {
+ * struct list_head *prev, *next;
+ * };
+ *
+ * typedef TCON_WRAP(struct list_head, char *canary) string_list_t;
+ *
+ * // More complex: mapping from one type to another.
+ * struct map {
+ * void *contents;
+ * };
+ *
+ * typedef TCON_WRAP(struct map, char *charp_canary; int int_canary)
+ * int_to_string_map_t;
+ */
+#define TCON_WRAP(basetype, decls) \
+ union { \
+ basetype _base; \
+ struct { \
+ decls; \
+ } *_tcon; \
+ }
+
+/**
+ * TCON_WRAP_INIT - an initializer for a variable declared with TCON_WRAP
+ * @...: Initializer for the base type (treated as variadic so commas
+ * can be included)
+ *
+ * Converts converts an initializer suitable for a base type into one
+ * suitable for that type wrapped with TCON_WRAP.
+ *
+ * Example:
+ * TCON_WRAP(int, char *canary) canaried_int = TCON_WRAP_INIT(17);
+ */
+#define TCON_WRAP_INIT(...) \
+ { ._base = __VA_ARGS__, }
+
+/**
+ * tcon_unwrap - Access the base type of a TCON_WRAP
+ * @ptr: pointer to an object declared with TCON_WRAP
+ *
+ * tcon_unwrap() returns a pointer to the base type of the TCON_WRAP()
+ * object pointer to by @ptr.
+ *
+ * Example:
+ * TCON_WRAP(int, char *canary) canaried_int;
+ *
+ * *tcon_unwrap(&canaried_int) = 17;
+ */
+#define tcon_unwrap(ptr) (&((ptr)->_base))
+
/**
* tcon_check - typecheck a typed container
* @x: the structure containing the TCON.
#define tcon_check(x, canary, expr) \
(sizeof((x)->_tcon[0].canary == (expr)) ? (x) : (x))
+/**
+ * tcon_check_ptr - typecheck a typed container
+ * @x: the structure containing the TCON.
+ * @canary: which canary to check against.
+ * @expr: the expression whose type must match &TCON (not evaluated)
+ *
+ * This macro is used to check that the expression is a pointer to the type
+ * expected for this structure (note the "useless" sizeof() argument
+ * which contains this comparison with the type canary), or NULL.
+ *
+ * It evaluates to @x so you can chain it.
+ */
+#define tcon_check_ptr(x, canary, expr) \
+ (sizeof(&(x)->_tcon[0].canary == (expr)) ? (x) : (x))
+
+
+/**
+ * tcon_type - the type within a container (or void *)
+ * @x: the structure containing the TCON.
+ * @canary: which canary to check against.
+ */
+#if HAVE_TYPEOF
+#define tcon_type(x, canary) __typeof__((x)->_tcon[0].canary)
+#else
+#define tcon_type(x, canary) void *
+#endif
+
+/**
+ * tcon_sizeof - the size of type within a container
+ * @x: the structure containing the TCON.
+ * @canary: which canary to check against.
+ */
+#define tcon_sizeof(x, canary) sizeof((x)->_tcon[0].canary)
+
+/**
+ * TCON_VALUE - encode an integer value in a type canary
+ * @canary: name of the value canary
+ * @val: positive integer compile time constant value
+ *
+ * This macro can be included inside the declarations in a TCON() or
+ * TCON_WRAP(), constructing a special "type" canary which encodes the
+ * integer value @val (which must be a compile time constant, and a
+ * positive integer in the range of size_t).
+ */
+#define TCON_VALUE(canary, val) char _value_##canary[val]
+
+/**
+ * tcon_value - retrieve the value of a TCON_VALUE canary
+ * @x: the structure containing the TCON
+ * @canary: name of the value canary
+ *
+ * This macros expands to the value previously encoded into a TCON
+ * using TCON_VALUE().
+ */
+#define tcon_value(x, canary) tcon_sizeof(x, _value_##canary)
+
+/**
+ * tcon_ptr_type - pointer to the type within a container (or void *)
+ * @x: the structure containing the TCON.
+ * @canary: which canary to check against.
+ */
+#if HAVE_TYPEOF
+#define tcon_ptr_type(x, canary) __typeof__(&(x)->_tcon[0].canary)
+#else
+#define tcon_ptr_type(x, canary) void *
+#endif
/**
* tcon_cast - cast to a canary type for this container (or void *)
* platform doesn't HAVE_TYPEOF, then it casts to void * (which will
* cause a warning if the user doesn't expect a pointer type).
*/
-#if HAVE_TYPEOF
-#define tcon_cast(x, canary, expr) ((__typeof__((x)->_tcon[0].canary))(expr))
-#else
-#define tcon_cast(x, canary, expr) ((void *)(expr))
-#endif
+#define tcon_cast(x, canary, expr) ((tcon_type((x), canary))(expr))
+#define tcon_cast_ptr(x, canary, expr) ((tcon_ptr_type((x), canary))(expr))
#endif /* CCAN_TCON_H */