10.8. Primitives¶

Primitives are Self methods implemented by the virtual machine. The first character of a primitive’s selector is an underscore (‘_’). You cannot define primitives yourself (unless you modify the Virtual Machine), nor can you define slots beginning with an underscore.

10.8.1. Primitive failures¶

Every primitive call can take an optional argument defining how errors should be handled for this call. To do this, the primitive is extended with an IfFail: argument. For example, _AsObject becomes _AsObjectIfFail:, and _IntAdd: becomes _IntAdd:IfFail:.

> 3 _IntAdd: ’a’ IfFail: [ | :error. :name |
(name, ’ failed with ’, error, ’.’) printLine. 0 ]
_IntAdd: failed with badTypeError.
0        "The primitive returns the result of evaluating the failure block."
>

When a primitive fails, if the primitive call has an IfFail: part, the message value:With: is sent to the IfFail: argument, passing two strings: the name of the primitive and an error string indicating the reason for failure. If the failing primitive call does not have an IfFail: part, the message primitive:FailedWith: is sent to the receiver of the primitive call with the same two strings as arguments.

The result returned by the error handler becomes the result of the primitive operation (0 in our example); execution then continues normally. If you want the program to be aborted, you have to do this explicitly within the error handler, for example by calling the standard error: method defined in the default world.

The following table lists the error string prefixes passed by the VM to indicate the reason of the primitive failure. If the error string consists of more than the prefix it will reveal more details about the error.

Table 10.5 Primitive failures¶
Prefix	Description
primitiveNotDefinedError	Primitive not defined.
primitiveFailedError	General primitive failure (for example, an argument has an invalid value).
badTypeError	The receiver or an argument has the wrong type.
badTypeSealError	Proxy’s type seal did not match expected type seal.
divisionByZeroError	Division by zero.
overflowError	Integer overflow. This can occur in integer arithmetic primitives or in UNIX (when the result is too large to be represented as an integer).
badSignError	Integer receiver or argument has wrong sign.
alignmentError	Bad word alignment in memory.
badIndexError	The vector index (e.g. in `_At:`) is out of bounds (too large or negative).
badSizeError	An invalid size of a vector was specified, e.g. attempting to clone a vector with a negative size (see `_Clone:Filler:` and `_CloneBytes:Filler:` below).
reflectTypeError	A mirror primitive was applied to the wrong kind of slot, e.g. `_MirrorParentGroupAt:` to a slot that isn’t a parent slot.
outOfMemoryError	A primitive could not complete because its results would not fit in the existing space.
stackOverflowError	The stack overflowed during execution of the primitive or program.
slotNameError	Illegal slot name.
argumentCountError	Wrong number of arguments.
unassignableSlotError	This slot is not assignable.
lonelyAssignmentSlotError	Assignment slot must have a corresponding data slot.
parallelTWAINSError	Can not invoke TWAINS primitive (another process is already using it).
noProcessError	This process does not exist.
noActivationError	This method activation does not exist.
noReceiverError	This activation has no receiver.
noParentSlot	This activation has no lexical parent.
noSenderSlot	This activation has no sender slot.
deadProxyError	This proxy is dead and can not be used.
liveProxyError	This proxy is live and can not be used to hold a proxy result.
wrongNoOfArgsError	Wrong number of arguments was supplied with call of foreign function.
nullPointerError	Foreign function returned null pointer.
nullCharError	Can not pass byte vector containing null char to foreign function expecting a string.
prematureEndOfInputError	Premature end of input during parsing.
noDynamicLinkerError	Primitive depends on dynamic linker which is not available in this system.
EPERM, ENOENT, …	These errors are returned by a UNIX primitive if a UNIX system call executed by the primitive fails. The UNIX error codes are defined in `/usr/include/sys/errno.h`; see this file for details on the roughly 90 different UNIX error codes.

The _ErrorMessage primitive, sent to an error string returned by any primitive, returns a more descriptive version of the error message; this is especially useful for UNIX errors.

10.8.2. Available primitives¶

A complete list of primitives can be obtained by sending primitiveList to primitives. Documentation for a primitive (such as _Clone), can be obtained using at:, thus:

primitives at: ’_Clone’

A list of primitive names matching a pattern can be obtained thus:

primitives match: ’_Memory*’

Some points to note when browsing primitives:

Since strings are special kinds of byte vectors, primitives taking byte vectors as arguments can usually take strings. The exception is that canonical strings cannot be passed to primitives that modify the object.

Integer arithmetic primitives take integer receivers and arguments; floating-point arithmetic primitives take floating-point receivers and arguments.

All comparison primitives return either true or false. Integer comparison primitives take integer receivers and arguments; floating-point comparison primitives take floating-point receivers and arguments.

The receiver of a mirror primitive must be a mirror (unless otherwise noted)