FreeBSD Manual Pages
AG_VARIABLE(3) Library Functions Manual AG_VARIABLE(3) NAME AG_Variable -- agar object variables SYNOPSIS #include <agar/core.h> DESCRIPTION In the Agar object system, each AG_Object(3) instance has a set of typed variables. Variables can be named (referenced by a string key) or anonymous (referenced by an AG_Variable pointer). Discrete types include: • Integers (e.g., int, Uint, long, Sint16, Uint64). • Real numbers (e.g., float, double, long double). • C strings (unbounded; auto-allocated). • Generic pointers. • Functions. Typed references (or "pointer variables") are also supported. Option- ally, pointer variables can be configured to acquire an AG_Mutex(3) locking device prior to accessing the data. Base reference types in- clude: • Integers (e.g., int *, Uint *, long *, Sint16 *, Uint64 *). • Real numbers (e.g., float *, double *, long double *). • Bits in a fixed-size word (per given bitmask). • Bounded C strings (in fixed-size buffer). • Agar objects (pointer to AG_Object(3)). • Proxy for another AG_Variable in an external AG_Object(3). GENERIC INTERFACE int AG_Defined(AG_Object *obj, const char *name) AG_Variable * AG_GetVariable(AG_Object *obj, const char *name, void **data) AG_Variable * AG_AccessVariable(AG_Object *obj, const char *name) AG_Variable * AG_FetchVariable(AG_Object *obj, const char *name, enum ag_variable_type type) AG_Variable * AG_FetchVariableOfType(AG_Object *obj, const char *name, enum ag_variable_type type) void AG_LockVariable(AG_Variable *var) void AG_UnlockVariable(AG_Variable *var) AG_Size AG_PrintVariable(char *dst, AG_Size len, AG_Variable *var) void AG_CopyVariable(AG_Variable *Vdst, const AG_Variable *Vsrc) void AG_DerefVariable(AG_Variable *Vdst, const AG_Variable *Vsrc) int AG_CompareVariables(const AG_Variable *a, const AG_Variable *b) void AG_Unset(AG_Object *obj, const char *name) void AG_VariableSubst(AG_Object *obj, const char *s, char *dst, AG_Size dst_len) AG_Defined() returns 1 if the variable name is defined under the object obj, otherwise it returns 0. The object obj must be locked. AG_GetVariable() searches for a variable name under obj and returns a pointer to the corresponding AG_Variable in a locked condition. The caller must use AG_UnlockVariable() when finished accessing the vari- able data. A pointer to the data itself is also returned in the data argument. 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. Both AG_GetVariable() and AG_AccessVariable() return NULL if the named vari- able 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 cre- ated and returned. Raises an exception if insufficient memory is available. The AG_FetchVariableOfType() variant works like AG_FetchVariable(), ex- cept that if the variable exists and is of a different type, then it is 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 lock- ing device associated with the specified variable. AG_PrintVariable() generates a string from the value of variable var. The string is written to the fixed-size buffer dst (of size len). AG_PrintVariable() returns the length of the string it tried to create. 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 dupli- cated, and pointers to strings are turned into discrete strings. The AG_CompareVariables() compares the value of two variables, return- ing 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). 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. 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 vari- able. 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 Uint AG_GetUint(AG_Object *obj, const char *name) void AG_InitUint(AG_Variable *var, Uint val) AG_Variable * AG_SetUint(AG_Object *obj, const char *name, Uint val) AG_Variable * AG_BindUint(AG_Object *obj, const char *name, Uint *pVal) AG_Variable * AG_BindUintMp(AG_Object *obj, const char *name, Uint *pVal, AG_Mutex *lock) int AG_GetInt(AG_Object *obj, const char *name) void AG_InitInt(AG_Variable *var, int val) AG_Variable * AG_SetInt(AG_Object *obj, const char *name, int val) AG_Variable * AG_BindInt(AG_Object *obj, const char *name, int *pVal) AG_Variable * AG_BindIntMp(AG_Object *obj, const char *name, int *pVal, AG_Mutex *lock) Uint8 AG_GetUint8(AG_Object *obj, const char *name) void AG_InitUint8(AG_Variable *var, Uint8 val) AG_Variable * AG_SetUint8(AG_Object *obj, const char *name, Uint8 val) AG_Variable * AG_BindUint8(AG_Object *obj, const char *name, Uint8 *pVal) AG_Variable * AG_BindUint8Mp(AG_Object *obj, const char *name, Uint8 *pVal, AG_Mutex *lock) Sint8 AG_GetSint8(AG_Object *obj, const char *name) void AG_InitSint8(AG_Variable *var, Sint8 val) AG_Variable * AG_SetSint8(AG_Object *obj, const char *name, Sint8 val) AG_Variable * AG_BindSint8(AG_Object *obj, const char *name, Sint8 *pVal) AG_Variable * AG_BindSint8Mp(AG_Object *obj, const char *name, Sint8 *pVal, AG_Mutex *lock) Uint16 AG_GetUint16(AG_Object *obj, const char *name) void AG_InitUint16(AG_Variable *var, Uint16 val) AG_Variable * AG_SetUint16(AG_Object *obj, const char *name, Uint16 val) AG_Variable * AG_BindUint16(AG_Object *obj, const char *name, Uint16 *pVal) AG_Variable * AG_BindUint16Mp(AG_Object *obj, const char *name, Uint16 *pVal, AG_Mutex *lock) Sint16 AG_GetSint16(AG_Object *obj, const char *name) void AG_InitSint16(AG_Variable *var, Sint16 val) AG_Variable * AG_SetSint16(AG_Object *obj, const char *name, Sint16 val) AG_Variable * AG_BindSint16(AG_Object *obj, const char *name, Sint16 *pVal) AG_Variable * AG_BindSint16Mp(AG_Object *obj, const char *name, Sint16 *pVal, AG_Mutex *lock) Uint32 AG_GetUint32(AG_Object *obj, const char *name) void AG_InitUint32(AG_Variable *var, Uint32 val) AG_Variable * AG_SetUint32(AG_Object *obj, const char *name, Uint32 val) AG_Variable * AG_BindUint32(AG_Object *obj, const char *name, Uint32 *pVal) AG_Variable * AG_BindUint32Mp(AG_Object *obj, const char *name, Uint32 *pVal, AG_Mutex *lock) Sint32 AG_GetSint32(AG_Object *obj, const char *name) void AG_InitSint32(AG_Variable *var, Sint32 val) AG_Variable * AG_SetSint32(AG_Object *obj, const char *name, Sint32 val) AG_Variable * AG_BindSint32(AG_Object *obj, const char *name, Sint32 *pVal) AG_Variable * AG_BindSint32Mp(AG_Object *obj, const char *name, Sint32 *pVal, AG_Mutex *lock) Uint64 AG_GetUint64(AG_Object *obj, const char *name) void AG_InitUint64(AG_Variable *var, Uint64 val) AG_Variable * AG_SetUint64(AG_Object *obj, const char *name, Uint64 val) AG_Variable * AG_BindUint64(AG_Object *obj, const char *name, Uint64 *pVal) AG_Variable * AG_BindUint64Mp(AG_Object *obj, const char *name, Uint64 *pVal, AG_Mutex *lock) Sint64 AG_GetSint64(AG_Object *obj, const char *name) void AG_InitSint64(AG_Variable *var, Sint64 val) AG_Variable * AG_SetSint64(AG_Object *obj, const char *name, Sint64 val) AG_Variable * AG_BindSint64(AG_Object *obj, const char *name, Sint64 *pVal) AG_Variable * AG_BindSint64Mp(AG_Object *obj, const char *name, Sint64 *pVal, AG_Mutex *lock) These functions provide an interface to both natural and fixed-size in- tegers. The Uint64 and Sint64 types are only available if AG_HAVE_64BIT is defined. REAL NUMBERS float AG_GetFloat(AG_Object *obj, const char *name) void AG_InitFloat(AG_Variable *var, float val) AG_Variable * AG_SetFloat(AG_Object *obj, const char *name, float val) AG_Variable * AG_BindFloat(AG_Object *obj, const char *name, float *pVal) AG_Variable * AG_BindFloatMp(AG_Object *obj, const char *name, float *pVal, AG_Mutex *lock) double AG_GetDouble(AG_Object *obj, const char *name) void AG_InitDouble(AG_Variable *var, double val) AG_Variable * AG_SetDouble(AG_Object *obj, const char *name, double val) AG_Variable * AG_BindDouble(AG_Object *obj, const char *name, double *pVal) AG_Variable * AG_BindDoubleMp(AG_Object *obj, const char *name, double *pVal, AG_Mutex *lock) These functions provide an interface to floating-point numbers. C STRINGS AG_Size AG_GetString(AG_Object *obj, const char *name, char *dst, AG_Size dst_size) char * AG_GetStringDup(AG_Object *obj, const char *name) char * AG_GetStringP(AG_Object *obj, const char *name) void AG_InitString(AG_Variable *var, const char *s) AG_Variable * AG_SetString(AG_Object *obj, const char *name, const char *s) AG_Variable * AG_SetStringF(AG_Object *obj, const char *name, const char *fmt, ...) AG_Variable * AG_SetStringNODUP(AG_Object *obj, const char *name, const char *s) AG_Variable * AG_BindString(AG_Object *obj, const char *name, char *s, AG_Size len) AG_Variable * AG_BindStringMp(AG_Object *obj, const char *name, char *s, AG_Size len, AG_Mutex *lock) These functions provide an interface to C strings. A string variable may contain an unbounded (auto-allocated) string or it may reference a bounded string (i.e., a string contained in a 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 contents of a string variable. If the copy cannot be allocated, NULL is returned. The returned string should be freed with AG_Free(3) after use. 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()). Auto-allo- cated strings set by AG_SetString() may be accessed safely without locking as long as the parent object is 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 du- plicated 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 void * AG_GetPointer(AG_Object *obj, const char *name) void AG_InitPointer(AG_Variable *var, void *val) AG_Variable * AG_SetPointer(AG_Object *obj, const char *name, void *val) AG_Variable * AG_BindPointer(AG_Object *obj, const char *name, void **pVal) AG_Variable * AG_BindPointerMp(AG_Object *obj, const char *name, void **pVal, AG_Mutex *lock) These functions provide an interface to generic pointer types. FUNCTIONS AG_Variable * AG_SetFn(AG_Object *obj, const char *name, AG_EventFn fn, const char *fmt, ...) AG_SetFn() sets the value of a function pointer variable to the speci- fied function fn and optional function arguments fmt. The object must be locked. See AG_Event(3) for more information on the argument for- mat. BITS AG_Variable * AG_BindFlag(AG_Object *obj, const char *name, Uint *pVal, Uint bitmask) AG_Variable * AG_BindFlagMp(AG_Object *obj, const char *name, Uint *pVal, Uint bitmask, AG_Mutex *lock) AG_Variable * AG_BindFlag8(AG_Object *obj, const char *name, Uint8 *pVal, Uint8 bitmask) AG_Variable * AG_BindFlag8Mp(AG_Object *obj, const char *name, Uint8 *pVal, Uint8 bitmask, AG_Mutex *lock) AG_Variable * AG_BindFlag16(AG_Object *obj, const char *name, Uint16 *pVal, Uint16 bitmask) AG_Variable * AG_BindFlag16Mp(AG_Object *obj, const char *name, Uint16 *pVal, Uint16 bitmask, AG_Mutex *lock) AG_Variable * AG_BindFlag32(AG_Object *obj, const char *name, Uint32 *pVal, Uint32 bitmask) AG_Variable * AG_BindFlag32Mp(AG_Object *obj, const char *name, Uint32 *pVal, Uint32 bitmask, AG_Mutex *lock) These functions provide an interface for binding to specific bits in integers. They follow the standard form, with an extra bitmask argu- ment. OBJECT-TO-OBJECT REFERENCES AG_Variable * AG_BindObject(AG_Object *obj, const char *name, AG_Object *varObj) AG_Variable * AG_BindVariable(AG_Object *obj, const char *name, AG_Object *varObj, const char *varKey) 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 re- leased from memory (or detached from the VFS) for as long as the refer- ence 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 ac- cessed, 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() creates an anonymous Object->Object reference to varObj (which is also removed 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: char name[AG_VARIABLE_NAME_MAX] Variable name (or "" = anonymous). AG_VariableType type Variable type (see <core/vari- able.h>). AG_Mutex *mutex Mutex protecting referenced data. union ag_variable_data data Stored data (see <core/variable.h>). EXAMPLES The following code tests if "delete-me" is defined and if so, deletes it: AG_Object *obj; if (AG_Defined(obj, "delete-me")) AG_Unset(obj, "delete-me"); The following code atomically increments a variable "value", which may be either an int or a float: void IncrementValue(AG_Object *obj) { AG_Variable *V; void *pValue; V = AG_AccessVariable(obj, "value", &pValue); switch (AG_VARIABLE_TYPE(V)) { case AG_VARIABLE_INT: (*(int *)pValue)++; break; case AG_VARIABLE_FLOAT: (*(float *)pValue) += 1.0f; break; } AG_UnlockVariable(obj); } The following code prints a string representation of a variable "value" to a fixed-size buffer buf: char buf[32]; AG_Object *obj; AG_Variable *V; if ((V = AG_AccessVariable(obj, "value")) == NULL) { AG_FatalError(NULL); } AG_PrintVariable(buf, sizeof(buf), V); AG_UnlockVariable(V); AG_Verbose("value = %s\n", buf); The following code atomically duplicates the contents of variable "copy-me" from one object objSrc to another object objDst: AG_Object *objSrc, *objDst; AG_Variable *Vsrc, *Vdst; Vsrc = AG_AccessVariable(objSrc, "copy-me"); Vdst = AG_AccessVariable(objDst, "copy-me"); if (Vsrc == NULL || Vdst == NULL) AG_FatalError(NULL); AG_CopyVariable(Vdst, Vsrc); if (AG_CompareVariables(Vsrc, Vdst) == 0) AG_Verbose("Copy successful\n"); AG_UnlockVariable(Vdst); AG_UnlockVariable(Vsrc); The following code uses object variable substitution to generate the string "Hello world!" into a fixed-size buffer: char buf[32]; AG_Object *obj; AG_SetString(obj, "the-string", "world"); AG_VariableSubst(obj, "Hello $(the-string)!", buf, sizeof(buf)); AG_Verbose("%s\n", buf); AG_Variable is used to represent AG_Object(3) instance variables and arguments passed to AG_Event(3) callback routines. In Agar-GUI, widgets use AG_Variable to reference data in memory (also known as "bindings"). Refer to the "BINDINGS" section of each widget's manual page for details. In Agar-GUI, the "value" of an AG_Numerical(3) spinbutton can be tied to an int, a float a mutex-protected Uint32, etc. 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" interface and AG_Widget(3) specific bindings. In Agar 1.6.0, Object->Object references appeared and AG_GetVariableLocked() was renamed AG_AccessVariable(). Functions ap- peared in Agar 1.7.0. Agar 1.7 December 21, 2022 AG_VARIABLE(3)
NAME | SYNOPSIS | DESCRIPTION | GENERIC INTERFACE | TYPE-SPECIFIC INTERFACES | INTEGERS | REAL NUMBERS | C STRINGS | GENERIC POINTERS | FUNCTIONS | BITS | OBJECT-TO-OBJECT REFERENCES | STRUCTURE DATA | EXAMPLES | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Variable&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>