7.6. Functions

7.6.1. byte_string_with_c_string

tom_object
byte_string_with_c_string (const char *s);

Return a newly allocated instance of tom.ByteString holding the characters from the zero-terminated string s. Obviously, the trailing zero is not contained in the returned ByteString.

7.6.2. byte_string_with_string

tom_object
byte_string_with_string (const char *s, int len);

Return a newly allocated instance of tom.ByteString holding the first len characters pointed to by s.

7.6.3. trt_assign_local_var

TRT_INLINE void *
trt_assign_local_var (void *object)

This function must be invoked if the object has just been assigned to a local variable and it is to live over a method invocation. Note that this is only necessary iff the stack protection policy implemented by the garbage collector (configured when building the TOM tools) is SP_PROTECT as opposed to SP_MARK (see config/default.h and config/target.h), so, probably (ahem), it isn't necessary.

[Obviously, the type of the argument should be tom_object instead of void *.]

7.6.4. trt_assign_object_var

TRT_INLINE void *
trt_assign_object_var (void *object, void *value);

This function must be invoked if the object pointed to by value has just been assigned to an object variable of the object. This is needed in case the garbage collector performs non-atomic runs. Thus, if you're writing library code in C, you must use this function. The compiler outputs calls to this function if the flag -fincremental-gc is provided on the command line (@pxref{Invoking tomc}). This feature is not supported yet in tesla.

[Obviously, the type of the two arguments should be tom_object instead of void *. However, since debugging a TOM program currently means debugging the (not so unreadable, to the trained eye at least) C code output by the compiler, the compiler types each object in the output to its C struct (as far as the compiler can know the layout at compile time). Hence, void * is used in some places where really tom_object should be used, to avoid numerous casts or warnings.]

7.6.5. trt_ext_address

void *
trt_ext_address (tom_object self, int extension_id);

trt_ext_address returns a pointer to the state information of the object self for the state introduced by the extension with the identity extension_id. This is the only legitimate way to obtain a pointer to some state held by some object. The only exception to this rule is the state information introduced by the State class (or instance), which, by definition, resides at offset 0 from self.

7.6.6. trt_selector_args_match

int
trt_selector_args_match (struct trt_selector_args *a,
                         struct trt_selector_args *b);

Return 1 if the number and types of the elements in a and b match, or 0 otherwise.

Normally, this test is very fast, since the resolver guarantees that for every pair of selector argument descriptions, a and b, if trt_selector_args_match returns 1, the a == b. However, in the context of dynamic-loading, selector argument descriptions can guaranteed to be unique, thus making trt_selector_args_match slightly more expensive.

7.6.7. trt_selector_named

selector *
trt_selector_named (char *s, int len);

Return the selector whose name matches the name held in the first len bytes pointed to by s. Return NULL if such a selector does not exist.

7.6.8. trt_type_name

char *
trt_type_name (enum trt_type_encoding type);

Return a zero terminated C string holding the name of the type. If the type is not a valid value, the string "<unknown type %d>" is returned, with the numeric value of the type replacing the %d.

[In the case of an unknown type being returned this function leaks memory, since the string returned is malloced.]

7.6.9. xmalloc

void *xmalloc (unsigned int n);
void *xcalloc (unsigned int n, unsigned int m);
void *xrealloc (void *p, unsigned int n);
void xfree (void *p);

Use these allocation manipulation routines instead of the x-less counterparts they are wrapping, since the `x' is a clue on some machines.