Module obj
Support for Refcounted Objects.
These are (currently) allocated with malloc and freed with free, but in addition always
carry a refcount (see obj_refcount). obj_ref increments this count, and obj_unref
decrements this count; when the count becomes zero, the object is freed. If the object
has an associated dispose function specified in obj_new, then this will be called first.
Unless OBJ_REF_ABBREV is defined, these are also defined as ref and unref; there is
a bulk dispose for multiple objects.
llib objects may specify a dispose function:
typedef struct {
int age;
char *name;
} Person;
static void Person_dispose(Person *p) {
obj_unref(p->name);
}
Person *person_new(int age, char *name) {
Person *p = obj_new(Person,Person_dispose);
p->age = age;
p->name = str_ref(name);
return p;
}
In this typical scenario, the dispose function decrements the reference
count of the name field when the Person is disposed; this will of course
only dispose the string if it hasn’t already been referenced elsewhere, which
permits flexible sharing of data. (We use str_ref specifically here because the
argument name may not be already a ref-counted string.)
Arrays carry their own size, accessible with array_len;
if created with array_new_ref, they will unref their elements when disposed.
Sequences are resizeable arrays. seq_add appends a new value
to a sequence. A sequence s is a pointer to an array of T. The underlying
array can always be accessed with *s, and the array will be sized-to-fit when
seq_array_ref is called.
See test-obj.c and test-seq.c
| FOR |
standard for-loop. |
| FOR_ARR |
for-loop over array. |
-
FOR
-
standard for-loop.
- i
loop variable.
- n
loop count.
-
FOR_ARR
-
for-loop over array.
- T
type
base type
- loop
type*
pointer
- array
type*
Usage:
FOR_ARR(int,pi,arr) printf("%d ",*pi);
-
obj_cast (T, o)
-
dynamically cast object to type.
Uses obj_is_instance
Parameters:
-
obj_refcount (p)
-
refcount of an object.
Will return -1 if it isn’t one of ours!
Parameters:
Returns:
int
-
array_len (arr)
-
length of array.
Parameters:
Returns:
int
-
obj_is_array (arr)
-
is this an array?.
Parameters:
Returns:
bool
-
obj_ref_array (arr)
-
is this a reference container array?
Parameters:
Returns:
bool
-
obj_elem_size (P)
-
size of this object.
For arrays, this is size of base type.
Parameters:
Returns:
int
-
obj_is_instance (P, name)
-
whether an object matches a type by name.
Parameters:
- P
const void *
- name
const char *
Returns:
bool
-
obj_new_type (T, optional)
-
allocate a new type
Parameters:
- T
type
- optional
DisposeFn
destructior
Returns:
T*
-
obj_new (T, optional)
-
allocate a new refcounted object.
Parameters:
- T
type
- optional
DisposeFn
destructior
Returns:
T*
-
obj_new_from_type (ti)
-
allocate a new object from type.
Parameters:
Returns:
void *
-
array_new (type, sz)
-
new array from type.
Parameters:
- type
T
name of type
- sz
int
size of array
Returns:
T*
-
array_new_ref (type, sz)
-
new array of refcounted objects.
Parameters:
- type
T
name of type
- sz
int
size of array
Returns:
T*
-
array_new_copy (type, buff, sz)
-
new array from buffer.
Parameters:
- type
T
name of type
- buff
T*
- sz
int
size of array
-
str_new (s)
-
create a refcounted string copy.
Parameters:
Returns:
char *
-
str_new_size (sz)
-
create a refcounted string of given size
Parameters:
Returns:
char *
-
str_cpy (s)
-
make a refcounted string from an arbitrary string.
Parameters:
Returns:
char *
-
obj_ref (object)
-
increase reference count (
ref).
Parameters:
Returns:
T
-
obj_unref (P)
-
decrease reference count (
unref).
When this goes to zero, free the object and call the
dispose function, if any.
Parameters:
-
obj_unref_v (...)
-
decrease ref count for multiple values (
dispose).
Parameters:
-
str_ref (s)
-
increase the refcount of a string.
If this is not one of “our strings”, we
create a new refcounted string, otherwise
proceed as with obj_ref.
Parameters:
Returns:
const char *
-
obj_apply_varargs (o, fn, ...)
-
apply a function to all arguments.
If
o is not NULL, then call fn(o,arg), otherwise
call fn(arg).
Parameters:
-
obj_apply (dest, setter, src, getter)
-
get from a source and put to a destination.
Parameters:
- dest
destination object
- setter
function of dest and the gotten object
- src
source object
- getter
function of
src to call repeatedly until it returns NULL
-
array_copy (P, i1, i2)
-
get a slice of an array.
Parameters:
- P
void *
the array
- i1
int
lower bound
- i2
int
upper bound (can be -ve; -1 is up to end, -2 is one less than end, etc)
Returns:
void *
-
array_resize (P, newsz)
-
resize an array.
Parameters:
- P
void *
the array
- newsz
int
the new size
Returns:
void *
-
array_sort (P, kind, ofs)
-
sort an array.
Parameters:
- P
T*
the array
- kind
int
either
ARRAY_INT or ARRAY_STR
- ofs
int
offset into each item
-
array_sort_struct_ptr (A, type, field)
-
sort an array of structs by integer/pointer field
Parameters:
- A
T*
the array
- type
T
the struct
- field
the name of the struct field
-
array_sort_struct_str (A, type, field)
-
sort an array of structs by string field
Parameters:
- A
T*
the array
- type
T
the struct
- field
the name of the struct field
-
seq_new (T)
-
create a plain sequence of a type
Parameters:
-
seq_new_ref (T)
-
create a sequence of a refcounted type
Parameters:
-
seq_new_array (arr)
-
create a sequence from an existing array.
Parameters:
Returns:
void *
-
seq_add (s, v)
-
add a value to a sequence.
Parameters:
- s
the sequence
- v
the value
-
seq_add_items (s)
-
add arbitrary number of values to a sequence.
The values are implicitly terminated with
NULL, so
this won’t work for arbitrary integers.
Parameters:
-
seq_remove (s, pos, len)
-
remove values from a sequence.
Parameters:
- s
the sequence
- pos
int
position
- len
int
number of values
-
seq_insert (s, pos, array, sz)
-
insert values into a sequence.
Parameters:
- s
the sequence
- pos
int
position
- array
of values
- sz
int
number of values (-1 means use array_len)
-
seq_adda (s, array, sz)
-
extend sequence with array of values.
Parameters:
- s
the sequence
- array
of values
- sz
int
number of values (-1 means use array_len)
-
seq_add_ptr (sp, p)
-
add a pointer value to a sequence.
Parameters:
-
seq_array_ref (sp)
-
get the array from a sequence.
(This will transfer ownership, shrink to fit,
and unref the sequence.)
Parameters:
Returns:
void *