br_resource_class
Once the structure is initialised, it is registered using BrResClassAdd()
325
typedef
brmem.h
for precise declaration and ordering)
br_uint_8 res_class Resource memory class
br_resourcefree_cbfn* free_cb Resource destructor
char * identifier Resource class name
BrResAllocate()
48
, BrResFree()
51
, BrResAdd()
49
, BrResRemove()
51
, BrResStrDup()
49
, BrResSize()
50
, BrResClass()
49
, BrResChildEnum()
50
.
BrMemAllocate()
55
, BrMemCalloc()
55
, BrMemInquire()
55
, BrMemFree()
56
, BrMemStrDup()
55
.
br_allocator
99
.
Members
Primary
The memory class of the new resource class. See Memory Classes for a description of possible values. Only values between br_uint_8 res_class
BR_MEMORY_APPLICATION
+1
and BR_MEMORY_MAX
-1
(inclusive) should be used.
This is a pointer to the destructor function (See br_resourcefree_cbfn * free_cb
br_resourcefree_cbfn
331) it may be
Null
if not required. Note that this function is not used to free the memory of the resource. It is simply an opportunity for the application to perform any other housekeeping functions indicated by the destruction of the resource. The resource is destroyed after the destructor returns.
For example, a user defined resource may be of structures containing pointers to reference counted (non-resource) items. In such a case, the referenced item will need to be dereferenced.
char * identifier
Null
if not required). A string constant is recommended. The alternative is to use something like:
my_res_class=BrResAllocate(NULL,sizeof(br_resource_class), BR_MEMORY_RESOURCE_CLASS); my_res_class->identifier=BrResStrDup(my_res_class,"MyClass");
BrResClassAdd()
Declaration:
br_resource_class* BrResClassAdd(br_resource_class* rclass)
Arguments:
br_resource_class * rclass
A non-Null
pointer to a resource class. The res_class
member of rclass
must be set to a valid, unused class ID between BR_MEMORY_APPLICATION
+1
and BR_MEMORY_MAX
-1
(inclusive).
Preconditions: Between
BrBegin()
10
& BrEnd()
11
.Result:
br_resource_class *
Returns a pointer to the resource class or Null
if unsuccessful.
Remarks: Remember, that
rclass
must point to a resource class structure that will remain valid until the class is removed.
A non-
Number of new resource classes to create.
Description:
Create several new resource classes.BrResClassAddMany()
br_uint_32 BrResClassAddMany(br_resource_class* const* items, int n)
br_resource_class * const * items
Null
pointer to a series of pointers to resource classes. The res_class
member of each resource class structure pointed to by items
must be set to a valid, unused class ID between BR_MEMORY_APPLICATION
+1
and BR_MEMORY_MAX
-1
(inclusive).int n
BrBegin()
10 &
BrEnd()
11.
Result:
br_uint_32
Returns the number of resource classes successfully created.
Remarks: Remember, that each resource class structures must remain valid until it is removed.
A non-
Description:
Remove a resource class from use.BrResClassRemove()
br_resource_class* BrResClassRemove(br_resource_class* rclass)
br_resource_class * rclass
Null
pointer to a resource class (that has been previously created using BrResClassAdd()
325
Preconditions: Between
BrBegin()
10
& BrEnd()
11
.Result:
br_resource_class *
Returns a pointer to the removed resource class.
A non-
Description:
Remove a number of resource classes from use.BrResClassRemoveMany()
br_uint_32 BrResClassRemoveMany(br_resource_class* const* items, int n)
br_resource_class * const * items
Null
pointer to an array of pointers to resource classes (all having previously been created using BrResClassAdd()
325
int n
Number of resource classes to remove from use.
Preconditions: Between
BrBegin()
10
& BrEnd()
11
.Result:
br_uint_32
Returns the number of resource classes successfully removed from use.
identifier
has been allocated from the heap. Do not use the same structure for different resource classes.
Access & Maintenance
While a current resource class, the members should not be changed. No maintenance required. Referencing & Lifetime
The structure must remain valid until the class is removed using BrResClassRemove()
326. BRender will not necessarily make a copy of the
br_resource_class
324
Initialisation
The members should be set before the structure is passed to BrResClassAdd()
325.
Search pattern.
Returns a pointer to the resource class if found, otherwise
Search pattern.
A pointer to an array of pointers to resource classes.
The maximum number of resource classes to find.
Returns the number of resource classes found. The pointer array is filled with pointers to the resource classes.
A pointer to a call-back function.
Returns a pointer to the old call-back function.
Search pattern.
Returns the number of resource classes matching the search string.
Search pattern.
A pointer to a call-back function.
An optional argument to pass to the call-back function.
Returns the first non-zero call-back return value, of zero if all resource classes are enumerated.
Construction & Destruction
The structure should ideally be statically constructed, but could be constructed and destroyed as in the following code:
br_resource_class* my_res_class;
my_res_class=BrResAllocate(NULL,sizeof(br_resource_class),
BR_MEMORY_RESOURCE_CLASS);
... /* Set members */
#define MY_RES_CLASS
BR_MEMORY_APPLICATION
+1
my_res_class->res_class=MY_RES_CLASS
;
my_res_class->free_cb=NULL;
my_res_class->identifier="MyResClass";
BrResClassAdd(my_res_class);
...
BrResFree(my_res_class);
Supplementary
The identifier
may be used to specify a resource class by name. Not recommended for intensive use. Locate resources, and keep a record of pointers. The following functions provide searching, counting and enumeration facilities for resource classes.
Description:
Find a resource class in the registry by name. A call-back function can be set up to be called if the search is unsuccessful. The search pattern can include the standard wild cards `*' and `?'.BrResClassFind()
br_resource_class* BrResClassFind(const char* pattern)
const char * pattern
br_resource_class *
NULL
. If a call-back exists and is called, the call-back's return value is returned.
Description:
Find a number of resource classes in the registry by name. The search pattern can include the standard wild cards `*' and `?'.BrResClassFindMany()
br_uint_32 BrResClassFindMany(const char* pattern, br_resource_class** items, int max)
const char * pattern
br_resource_class ** items
int max
br_uint_32
Description:
Set up a resource class find call-back. If BrResClassFindHook()
BrResClassFind()
328 is unsuccessful and a call-back has been set up, the call-back is passed the search pattern as its only argument. The call-back should then return a pointer to a substitute or default resource class.
br_resclass_find_cbfn* BrResClassFindHook(br_resclass_find_cbfn* hook)
br_resclass_find_cbfn * hook
br_resclass_find_cbfn *
br_resource_class BR_CALLBACK * example_callback(char* pattern)
{ br_resource_class default;
...
return(&default);
}
{ br_resource_class *rc;
...
BrResClassFindHook(&example_callback);
rc = BrResClassFind("non_existant_class");
}
Declaration:
BrResClassCount()
br_uint_32 BrResClassCount(const char* pattern)
const char * pattern
br_uint_32
Description:
Call a call-back function for every resource class matching a given search pattern. The call-back is passed a pointer to each matching resource class, and its second argument is an optional pointer supplied by the user. The search pattern can include the standard wild cards `*' and `?'. The call-back itself returns a BrResClassEnum()
br_uint_32
348 value. The enumeration will halt at any stage if the return value is non-zero.
br_uint_32 BrResClassEnum(char* pattern, br_resclass_enum_cbfn* callback, void* arg)
char * pattern
br_resclass_enum_cbfn * callback
void * arg
br_uint_32
br_uint_32 BR_CALLBACK example_callback(br_resource_class* item, void* arg)
{ br_uint_32 value;
...
return(value);
}
{ br_uint_32 ev;
...
ev = BrResClassEnum("pattern",&example_callback,NULL);
}
Generated with CERN WebMaker