FreeWRL/FreeX3D  3.0.0
Data Fields
cson_value Struct Reference

The core value type of this API. More...

#include <cson_amalgamation_core.h>

Data Fields

cson_value_api const * api
 The "vtbl" of type-specific operations. More...
 
void * value
 The raw value. More...
 
cson_counter_t refcount
 We use this to allow us to store cson_value instances in multiple containers or multiple times within a single container (provided no cycles are introduced). More...
 

Detailed Description

The core value type of this API.

It is opaque to clients, and only the cson public API should be used for setting or inspecting their values.

This class is opaque because stack-based usage can easily cause leaks if one does not intimately understand the underlying internal memory management (which sometimes changes).

It is (as of 20110323) legal to insert a given value instance into multiple containers (they will share ownership using reference counting) as long as those insertions do not cause cycles. However, be very aware that such value re-use uses a reference to the original copy, meaning that if its value is changed once, it is changed everywhere. Also beware that multi-threaded write operations on such references leads to undefined behaviour.

PLEASE read the ACHTUNGEN below...

ACHTUNG #1:

cson_values MUST NOT form cycles (e.g. via object or array entries).

Not abiding th Holy Law Of No Cycles will lead to double-frees and the like (i.e. undefined behaviour, likely crashes due to infinite recursion or stepping on invalid (freed) pointers).

ACHTUNG #2:

ALL cson_values returned as non-const cson_value pointers from any public functions in the cson API are to be treated as if they are heap-allocated, and MUST be freed by client by doing ONE of:

  • Passing it to cson_value_free().
  • Adding it to an Object or Array, in which case the object/array takes over ownership. As of 20110323, a value may be inserted into a single container multiple times, or into multiple containers, in which case they all share ownership (via reference counting) of the original value (meaning any changes to it are visible in all references to it).

Each call to cson_value_new_xxx() MUST eventually be followed up by one of those options.

Some cson_value_new_XXX() implementations do not actually allocate memory, but this is an internal implementation detail. Client code MUST NOT rely on this behaviour and MUST treat each object returned by such a function as if it was a freshly-allocated copy (even if their pointer addresses are the same).

ACHTUNG #3:

Note that ACHTUNG #2 tells us that we must always free (or transfer ownership of) all pointers returned bycson_value_new_xxx(), but that two calls to (e.g.) cson_value_new_bool(1) will (or might) return the same address. The client must not rely on the "non-allocation" policy of such special cases, and must pass each returned value to cson_value_free(), even if two of them have the same address. Some special values (e.g. null, true, false, integer 0, double 0.0, and empty strings) use shared copies and in other places reference counting is used internally to figure out when it is safe to destroy an object.

See Also
cson_value_new_array()
cson_value_new_object()
cson_value_new_string()
cson_value_new_integer()
cson_value_new_double()
cson_value_new_bool()
cson_value_true()
cson_value_false()
cson_value_null()
cson_value_free()
cson_value_type_id()

Definition at line 1486 of file cson_amalgamation_core.c.

Field Documentation

cson_value_api const* cson_value::api

The "vtbl" of type-specific operations.

All instances of a given logical value type share a single api instance.

Results are undefined if this value is NULL.

Definition at line 1493 of file cson_amalgamation_core.c.

cson_counter_t cson_value::refcount

We use this to allow us to store cson_value instances in multiple containers or multiple times within a single container (provided no cycles are introduced).

Notes about the rc implementation:

  • The refcount is for the cson_value instance itself, not its value pointer.
  • Instances start out with a refcount of 0 (not 1). Adding them to a container will increase the refcount. Cleaning up the container will decrement the count.
  • cson_value_free() decrements the refcount (if it is not already 0) and cleans/frees the value only when the refcount is 0.
  • Some places in the internals add an "extra" reference to objects to avoid a premature deletion. Don't try this at home.

Definition at line 1526 of file cson_amalgamation_core.c.

void* cson_value::value

The raw value.

Its interpretation depends on the value of the api member. Some value types require dynamically-allocated memory, so one must always call cson_value_free() to destroy a value when it is no longer needed. For stack-allocated values (which client could SHOULD NOT USE unless they are intimately familiar with the memory management rules and don't mind an occasional leak or crash), use cson_value_clean() instead of cson_value_free().

Definition at line 1504 of file cson_amalgamation_core.c.

The documentation for this struct was generated from the following file: