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 are supported:
"Pointer" variables can also reference typed data. Optionally, pointer variables can be configured to acquire a AG_Mutex(3) locking device prior to accessing the data. Supported reference types include:
There are other uses for AG_Variable besides representing AG_Object(3) variables. For instance, AG_Variable is 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
|
AG_Defined() returns 1 if the variable name is defined under the object obj, otherwise it returns 0. The object obj must be locked. The AG_GetVariable() function searches for a variable name under obj, and returns the matching AG_Variable in a locked condition (or NULL if undefined). If the variable is virtual function then it is evaluated implicitely. The caller must use AG_UnlockVariable() when finished accessing the variable data. A pointer to the data is also returned in the data argument if it is not NULL. If the variable is undefined, a fatal exception is raised. The AG_AccessVariable() function searches for a variable by name and returns the matching AG_Variable in a locked condition. The caller must use AG_UnlockVariable() when done accessing the data. Unlike AG_GetVariable(), AG_AccessVariable() does not evaluate virtual functions, and returns NULL if the variable is undefined. The AG_FetchVariable() function searches for a variable by name and type. If found, return the corresponding AG_Variable. If the variable is undefined then a new one of the specified type is automatically created and returned. Raises an exception if insufficient memory is available. The AG_FetchVariableOfType() variant works like AG_FetchVariable(), except that if the variable exists and is of a different type, then it is implicitely mutated into type and returned. Note: Unlike AG_GetVariable() and AG_AccessVariable(), AG_FetchVariable() and AG_FetchVariableOfType() do not return the AG_Variable locked. AG_LockVariable() and AG_UnlockVariable() acquire and release any locking device associated with the specified variable. AG_GetVariableVFS() searches through the VFS of AG_Object(3) (which has obj as its root) for a variable by name. The path argument is a string of the form "<object-path>:<variable-name>". If found, then the AG_Variable is returned in a locked condition. The caller must use AG_UnlockVariable() when done accessing the variable's data. AG_EvalVariable() evaluates a virtual function and copies the return value into the data field. Return 0 on success or -1 if the virtual function is undefined. Note: AG_GetVariable() calls this implicitely. AG_PrintVariable() returns a string representation of the value of variable var into a fixed-size buffer dst, of len bytes. AG_CopyVariable() copies the contents of a variable from Vsrc to Vdst. Pointer references are preserved. Discrete strings are duplicated. AG_DerefVariable() copies the contents of Vsrc to Vdst, converting pointer references to immediate values. Discrete strings are duplicated, and pointers to strings are turned into discrete strings. The AG_CompareVariables() compares the value of two variables, returning zero if they are identical. If they differ, the difference between the two first differing bytes is returned. If AG_CompareVariables() encounters pointer types, they are not dereferenced (rather the value of the pointer itself is compared). The AG_Set() sets an object-bound variable value using a format-string interface (see AG_PARSE_VARIABLE_ARGS()). AG_Unset() deletes the named object-bound variable. AG_VariableSubst() parses the string s for references of the form "$(foo)", and substitutes those references for the value of variable foo (under object obj). The substituted string is returned into fixed-size buffer dst, of size dst_size. |
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. If the variable is a virtual function, it is evaluated first. 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. AG_Bind<Type>Fn() creates or modifies a variable, tying the variable to a virtual function fn, which will be evaluated whenever the variable is read. Following the F fnargument is a variable list of optional AG_Event(3) style arguments to pass to the virtual function. |
INTEGERS
REAL NUMBERS
These functions provide an interface to floating-point numbers. The long double functions are only available if AG_HAVE_LONG_DOUBLE is defined. |
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() returns the contents of a string variable. The string is safely copied to fixed-size buffer dst, of size dst_size. Return 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. AG_GetStringP() returns a direct pointer to the buffer containing the string. If the variable is a virtual function, it is not evaluated. Warning: AG_GetStringP() is not free-threaded, so the object must be locked and calls should be protected by AG_LockVariable() (exceptionally, discrete strings set by AG_SetString() are safe to access without locking if the variable's parent object is locked). AG_InitString() initializes a AG_Variable structure with the given string, which is copied from s. The AG_InitStringNODUP() variant sets the s pointer without copying the string. The AG_SetString() function creates or modifies a string variable. The s argument is a C string which will be duplicated or copied. If the variable exists as a reference to a fixed-size buffer (i.e., it has been created by AG_BindString()), then the contents of s are copied to the buffer. If the buffer has insufficient space, the string is truncated. The s argument may be set to NULL (in which case further AG_GetString() calls will return NULL). The AG_SetStringNODUP() variant accepts a pointer to a dynamically-allocated string buffer. This buffer will be freed automatically when the parent object is destroyed. AG_PrtString() sets a string variable from a printf3 style format. AG_BindString() creates or modifies a variable referencing a fixed-size string buffer s, of size len. The AG_BindStringFn() variant ties the variable to a function fn. |
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_List(3), AG_Object(3), AG_Tbl(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. |
