SYNOPSIS
|
DESCRIPTION
In the Agar object system, each
AG_Object(3) instance has a set of typed variables.
Variables can be named (accessed by a string key), or anonymous (by pointer).
Basic types include:
Typed references (or "pointer variables") are also supported. Optionally, pointer variables can be configured to acquire a AG_Mutex(3) locking device prior to accessing the data. Reference types include:
Besides representing AG_Object(3) instance variables, there are many other uses for AG_Variable. For example, it is also used to represent arguments passed to AG_Event(3) callback functions. In Agar-GUI, widgets use Agar variables to reference data in memory (also known as "bindings"). For example, the "value" of an AG_Numerical(3) spinbutton can be tied to an int, a float a mutex-protected Uint32, etc. See the "BINDINGS" section of a widget's manual page for the list of bindings and types supported. |
GENERIC INTERFACE
TYPE-SPECIFIC INTERFACES
|
The following functions get and set variables of specific types.
AG_Get<Type>() returns the value of variable name under object obj with implicit dereferencing. If the variable is a pointer type then the value referenced by it is returned. The AG_Init<Type>() functions initialize an AG_Variable structure var with the specified value val. The AG_Set<Type>() functions set the value of variable name to the specified value val. Implicit dereferencing is done. If the variable does not exist, it is created. The AG_Bind<Type>() functions create or modify a typed pointer variable. The argument pVal is a pointer to the actual value. The AG_Bind<Type>Mp() variant accepts an extra lock argument, which is a mutex device (i.e., an AG_Mutex or pthread_mutex_t) to be acquired whenever the data referenced by pVal will be accessed. |
INTEGERS
These functions provide an interface to both natural and fixed-size integers. The Uint64 and Sint64 types are only available if AG_HAVE_64BIT is defined. |
REAL NUMBERS
These functions provide an interface to floating-point numbers. |
C STRINGS
These functions provide an interface to C strings. A string variable may contain an unbounded string, or reference an external fixed-size buffer. AG_GetString() copies the contents of a string variable to a fixed-size buffer dst of size dst_size and returns the number of bytes that would have been copied were dst_size unlimited. AG_GetStringDup() returns a newly-allocated copy of the string variable. If the string cannot be allocated, NULL is returned. The potentially-unsafe AG_GetStringP() returns a direct pointer to the buffer containing the string. It is not free-threaded (so the object must be locked, and calls protected by AG_LockVariable()). Note that discrete strings set by AG_SetString() are safe to access without locking as long as the variable's parent object is itself locked. AG_InitString() initializes a AG_Variable structure with the given string, which is copied from s. AG_SetString() sets the value of a string variable (possibly creating a new variable). The s argument is a C string which will be either duplicated or copied. If the given variable exists and is a reference to a fixed-size buffer (i.e., it was generated by a AG_BindString() call), then the contents of s are copied to the the referenced buffer. If the buffer is too small to fit the string, the string is safely truncated. The s argument may be set to NULL (in which case further AG_GetString() calls will also return NULL). The AG_SetStringF() variant accepts a printf(3) style format string argument. The potentially-unsafe AG_SetStringNODUP() variant accepts a pointer to a dynamically-allocated string buffer which will be free'd whenever the parent object is destroyed. AG_BindString() creates or modifies a variable referencing a fixed-size string buffer s, of size len. |
GENERIC POINTERS
These functions provide an interface to generic pointer types. |
BITS
These functions provide an interface for binding to specific bits in integers. They follow the standard form, with an extra bitmask argument. |
OBJECT-TO-OBJECT REFERENCES
The AG_BindObject() function creates an Object->Object reference and hard dependency to an external object varObj and return a P_OBJECT type Variable on success. A hard dependency implies that if both obj and varObj share the same VFS then Agar will not allow varObj to be released from memory (or detached from the VFS) for as long as the reference exists. The AG_BindVariable() function creates an Object->Variable reference to the variable called varKey under an external object varObj, returning a P_VARIABLE type Variable on success. Whenever this Variable is accessed, the external object will be locked and a copy of its variable varKey will be returned implicitely. Note: Circular references must be avoided. AG_BindVariable() implicitely creates an anonymous Object->Object reference to varObj (which is also removed implicitely by AG_Unset() or AG_ObjectFreeVariables(3) when no more Object->Variable references make use of the object). AG_BindObject() and AG_BindVariable() may fail and return NULL. |
STRUCTURE DATA
For the
AG_Variable structure:
|
SEE ALSO
| AG_Intro(3), AG_Event(3), AG_Object(3) |
HISTORY
| The AG_Variable interface first appeared in Agar 1.3.4. It replaced the older AG_Prop(3) interface, and widget bindings which were previously stored in AG_Widget(3) itself. AG_GetVariableLocked() was renamed AG_AccessVariable() in Agar 1.6.0. |
