8.68. File tom/State

class tom.State

inherits

Behaviour supers: All

variables

State isa;

Our class. The `State' class is an instance of the State meta-class. The same is true for every other class.

private int asi;

Information used, in cunning ways, by the runtime.

methods

instance (id)
  alloc;

Return a newly created instance of the receiving class. All values, apart from the isa will have been initialized to their default value.

instance (id)
  alloc int size;

Like plain alloc, but allocate space for size bytes instead of the size of an instance. size is rounded up if it is not large enough for an instance of the receiving class to fit.

int
  instanceSize;

Return the size of the instances of this class. This may change due to dynamic loading if no instance has yet been created.

boolean
  classp;

Return TRUE, since we're a class object.

boolean
  coding-permanent-object-p;

Return YES. This should not be changed; this method is used in situations where it is not known whether the object is a class or not. In other situations, where it is known to be a class, this method is not invoked as it is known to return YES.

boolean
  dump_simple_p;

Return YES.

class (id)
  kind;

Return the class of the receiving object, i.e. the value of isa.

ByteString
  name;

Return the name of this class.

int (n)
  num_instances;

Return the number of currently live direct instances of this class, non-transitively.

Unit (unit)
  unit
post
  unit != nil;

Return the unit of this class. The postcondition states that such a unit must exit.

instance (id)
  new;

Return a newly created and initialized instance of the receiving class.

OutputStream
  write OutputStream s;

Write a description of this class object to the stream s.

instance tom.State

inherits

Behaviour supers: All

variables

class (id) isa;

Our class.

private int asi;

Information used, in cunning ways, by the runtime.

methods

boolean
  classp;

Return FALSE, as we're an instance, and not a class.

protected void
    dump MutableKeyed done
  indent MutableByteString prefix
  simple boolean allow_simple
   level int level
      to OutputStream s;

Hard worker for dump.

id
  init;

Designated initializer. Does nothing.

class (id)
  kind;

Return the class of the receiving object.

void
  set_kind class (State) a_class;

Change the class of the receiving object (i.e., the isa) into the a_class. Currently both the original and the new class must carry exactly the same state. Looser restrictions could be implemented...

OutputStream
  write OutputStream s;

Write the class and address of the receiving object to the stream s.

OutputStream
  writeFields OutputStream s;

Subsidiary for write to allow subclasses to write their fields to the stream s. The default implementation does nothing.

void
  dealloc;

Invoked by the garbage collector when an object has become garbage. Some important notes apply to this method:

Do not message any other objects from within this method as they might have become garbage too.

Since class objects can not become garbage, it is safe to message class objects.

When overriding this method, it is not necessary to invoke State's implementation.

void
  gc_mark_elements;

This method is invoked by the garbage collector for instances which employ pointer typed instance variables, to have the receiving object mark the elements it references through said pointers. The default implementation marks the object referencing variables.

class tom.Recyclable

Recyclable is the class meant to help in cases where normal garbage collection provides suboptimal performance. It allows (but it does NOT require) manual object deallocation. To use, a simple call to [Recyclable recycle] frees the object. Note that there is no error checking, and calling methods from a recycled object results in an undefined behaviour.

Note that recycling is not mandatory. Unrecycled objects that are not needed any longer are freed in the normal GC passes. It is therefore not a good idea to spend too much effort (both development and runtime) on locating the objects that should be recycled - it is then more efficient to just rely on GC, and it is also less bug-prone.

Also note that not all the classes should be Recyclable - it is reserved for the exceptional cases, it may cause memory wastage, and in presence of generational GC, it may actually reduce performance.

inherits

State supers: State

variables

MutableObjectArray recycle_bin;

The Array with the recycled objects of this class.

methods

void
  load Indexed args;

Initialise the recycle_bin.

instance (id)
  alloc;

Override on [State alloc], this method tries to reuse a recycled object before allocating a fresh one.

instance tom.Recyclable

methods

void
  recycle;

Recycle the receiving object, allowing its reuse. Since this will not zero out the memory reserved for the object (or uninitialize it in any other way, it might be expedient (but not mandatory) to zero out the pointers from the object, so that GC can catch the referenced memory.