next up previous contents
Next: 4.12 fluke_region_set_state: set the Up: 4 Regions Previous: 4.10 fluke_region_reference: associates a

4.11 fluke_region_search: search for objects in a memory region

SYNOPSIS

void fluke_region_search(fluke_region_t *region, oskit_addr_t *offset, oskit_size_t size, fluke_obspec_t *obarray, unsigned *obarray_size);

DESCRIPTION

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:

struct fluke_obspec  {

		void		*ob;	/* VA of object in region's task */
		fluke_type_t	type;	/* object type */
	 
}

typedefstruct fluke_obspecfluke_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.

PARAMETERS

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.

ERRORS

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.


next up previous contents
Next: 4.12 fluke_region_set_state: set the Up: 4 Regions Previous: 4.10 fluke_region_reference: associates a

Utah Flux Research Group