void fluke_region_search(fluke_region_t *region, oskit_addr_t *offset, oskit_size_t size, fluke_obspec_t *obarray, unsigned *obarray_size);
Search part or all of the address range covered by a memory region for active objects, inserting their addresses and types into obarray. offset and size define the subset of the region to search. obarray_size must initially be set to the number of elements in the array. The obspec structure is defined as follows:
void *ob; /* VA of object in region's task */ fluke_type_t type; /* object type */}
typedef struct fluke_obspec fluke_obspec_t; where the type field indicates the type of the object and the ob field is a virtual address indicating the location of the object in the task over which region is defined. Note that this does not have to be the same task with which the calling thread is associated.
Threads calling fluke_region_search for regions in other tasks may need to perform appropriate address translation before using the returned address.
If all objects within the range fit into obarray, this operation will increment offset by size (to indicate the entire range was searched) and sets obarray_size to the number of elements not used in the array (i.e., the number of objects found is the original size minus the returned size).
If the array was too small to accommodate the number of objects found, the array is filled with the first obarray_size object descriptors and offset is adjusted to point somewhere after the last object recorded but before any following object in the range. obarray_size will be set to zero on return, indicating that the array was filled.
Hence, if the returned offset is equal to the end of the specified range, all objects within the range have been found. Otherwise, offset can be used as a starting point for a further search after either the array has been made larger or the object descriptors returned have been consumed so that the array can be reused. In this way, the caller never has to rescan the memory already searched.
If any of the pages in the specified address range are not currently mapped in the affected task's address space, then page faults will occur on those pages, causing them to be faulted in so they can be searched. It is implementation defined whether these page faults are read faults or write faults. Any pages causing other exceptions are silently skipped.
In Fluke implementations that guarantee protection between tasks, any objects found and returned by this routine are guaranteed to be ``safe'' for the caller to make object invocations on by the time this operation returns. If an object in the memory region was created by a different task, and that task performed illegal actions on that object that may have caused the object's state to become invalid (e.g. by overwriting the memory in which the object resides), then fluke_region_search will either cause the object to be ``repaired'' enough so that it can be safely accessed again, or else will destroy the object entirely, in which case no indication that the object ever existed will be provided to the caller.
- region
- The memory region being searched.
- offset
- On entry, the offset within the region at which to start the search. On return, an offset beyond the last object returned.
- size
- The size in bytes of the area of the region to be searched.
- obarray
- A pointer to the first element of the array to fill in with the address and type of each Fluke object found.
- obarray_size
- On entry, contains the number of available entries in the array. On return, contains the number of unused entries.
If any of the following errors is detected by the Fluke implementation, it causes the current thread to take a synchronous exception with one of the following codes. All of these have an implicit FLUKE_INSANITY_ prefix.
- NO_OBJECT
- region does not point to an active object.
- NOT_REGION
- The object pointed to by region is not a region object.
- INVALID_OBJECT
- The state of the region object has become invalid.
- INVALID_RANGE
- The specified offset or size parameters define an invalid range for the region.