This section describes, for each defined Fluke object type, the set of object invocations available for that type. Except where otherwise specified, all invocation parameters that are pointers to active objects must point to objects that appear in the current task, i.e. in the same task as the thread making the invocation.
Most invocations have no return value but may cause exceptions known as insanity traps. These traps are generated by a Fluke implementation in response to ``abnormal'' conditions such as invoking an operation on an invalid object. The intent is that these conditions represent programmatic errors that do not occur in a correctly functioning program. Detection and reporting of insanity conditions is implementation specific. The insanity conditions documented in this manual reflect those which might reasonably be detected and reported by a Fluke implementation.
There are a set of function common to all Fluke object types:
Creates an object of the specified type.
The caller provides a pointer to a fluke_object structure
which will hold the user portion of the fluke object's state.
This memory should be aligned naturally for the object type
and should contain no other objects.
After return from a create call,
the memory occupied by the object structure
should only be used in object invocations,
and not accessed directly (the result of direct accesses is undefined).
Objects have an initial default state,
but in many cases that default state is not very useful and
the new object is not ``usable'' until new state has been
set with fluke_object_set_state.
The object hash value is initialized by the system using an
implementation-dependent function.
Objects can only be created in memory which has
FLUKE_PROT_CREATE_OB
and FLUKE_PROT_WRITE
permissions enabled.
If not enabled,
attempts to create objects will cause a synchronous exception
(``page fault'') to be sent to the region keeper or, failing that,
to the thread or its associated task keeper.
Identical to fluke_create but allows explicit specification of the hash value via a second parameter. A value of zero for that parameter, causes the hash to be initialized by the Fluke implementation as with fluke_create.
Destroys an object.
The caller provided pointer should reference a valid object of the
correct type.
This implies that the call will also fail if the pointer is to an
object with corrupted state.
The only way to destroy ``corrupt'' objects is via
fluke_region_search.
After an object is destroyed,
the contents of the memory occupied by the object is undefined
and the memory is once again directly accessible.
Objects can only be destroyed in memory which has
FLUKE_PROT_WRITE permission enabled.
If not enabled,
attempts to destroy objects
will cause synchronous page fault exceptions.
Moves an object from one virtual address to another in the same task. The ``from'' argument must be a pointer to a valid object of the correct type. The ``to'' argument must be a pointer to raw memory as in a create call. After the call, the contents of the memory occupied by the ``from'' object is undefined and the memory is once again directly accessible. Moving an object requires FLUKE_PROT_WRITE permission to the source memory, FLUKE_PROT_CREATE_OB and FLUKE_PROT_WRITE to the destination. If the appropriate permissions are not allowed, attempts to move objects will cause synchronous page fault exceptions.
Associates a reference object with an object of the given type. The caller provides a pointer to a valid object of the appropriate type and a pointer to a valid reference object created via fluke_ref_create. The caller must have FLUKE_PROT_WRITE permission for both the object being referenced and the reference object itself. If the appropriate permissions are not allowed, attempts to reference objects will cause synchronous page fault exceptions.
Returns the complete state of an object. The object itself is unaffected by the call. The caller provides a pointer to a fluke_object_state structure for any simple state, and a list of pointers to valid reference objects for inter-object state. After the call, the state structure will be filled in and the reference objects will be associated with whatever the corresponding inter-object links referred to. The simple state pointer or any of the reference pointers may be zero, in which case the corresponding state is not returned. Calls failing due to ``insanity'' conditions leave the contents of any state structure undefined and reference objects possibly modified. The caller must have FLUKE_PROT_READ permission to the object. Otherwise, a synchronous page fault exception is generated.
Loads new state for an object. The arguments are identical to those of the corresponding fluke_object_get_state call. a pointer to a simple state structure and a list of pointers to valid reference objects. Any of the pointers may be zero, in which case the corresponding state is not loaded. All reference objects are copied; i.e. after the call, any references passed in will still be valid and can safely be destroyed. The effect of loading corrupt object state is undefined, the call may or may not return an error and the resulting state of the object is undefined. Calls failing due to ``insanity'' conditions leave the target object in an undefined, though always valid, state. For example, an object's references to other objects may be invalidated. The caller must have FLUKE_PROT_WRITE permission to the object. Otherwise, a synchronous page fault exception is generated.