7 The MLWorks Foreign Interface Library

7.6 The Object structure

A foreign object is an ML value which provides a means of both accessing and modifying foreign data from ML. Foreign objects are represented with the type object.

Foreign objects do not contain foreign data itself, but are instead associated with a location in a store object which contains foreign data. In short, a foreign object provides indirect access to foreign data, thus allowing objects to be freely copied or otherwise manipulated without replicating the foreign data itself. The disadvantage of this is that it permits many different objects to refer to the same foreign data, that is, it permits aliasing. An update to the foreign data through any one such object is an update that will be observed by all alias objects.

The requirements for representing foreign objects naturally differ depending on the foreign language being interfaced to. Some of the necessary features of, and possible operations upon, foreign objects will be the same whatever the foreign language.

However, foreign objects will probably have some language-specific aspects too. In particular, any notion of typing will be language specific. For this reason, the ML type that represents object objects is polymorphic, allowing for this dependence on language-specific aspects, such as typing.

The Object structure is, then, the generic implementation of foreign object representations and protocols.

As you will see below, there are several generic ways of inspecting a foreign object, but no (generic) ways of generating objects directly or modifying any existing characteristics they may have. The reason is that these are very much subject to the language-specific semantics of the appropriate data model. Accordingly, such operations are provided within the language-specific interfaces.

object

Type abbreviation

Specification:: type ('l_type)object
Description:
: Foreign objects have two main components: a value part and a type part. The value part refers to some raw information contained in an associated store workspace, while the type part defines how that raw information should be interpreted.
: The ML type of the language-specific information is provided via the ML type parameter 'l_type.

ReadOnly

Exception

Specification:: exception ReadOnly
Description:
: See WriteOnly, below.

WriteOnly

Exception

Specification:: exception WriteOnly
Description:
: The WriteOnly and ReadOnly exceptions are raised when an object attempts to access or update a store in a manner forbidden by the store's current read/write status. See the datatype object_mode, below.

object_mode

Datatype

Specification:: datatype object_mode = LOCAL_OBJECT | REMOTE_OBJECT
Description:
: Every object has an associated mode which governs the way in which foreign data can be accessed. In general, foreign objects access foreign data that is present locally, in store objects they are associated with.
: However, some foreign objects access raw foreign data that is not local to a store but somewhere remote. You may not need to copy the foreign data to a store to do what you want with such data. A local access method based around stores is not appropriate in that case.
: Object may therefore be in one of two modes: local or remote. An object in local mode can only access and modify data present within its associated store. An object in remote mode is located remotely to enable it to access foreign data without having first copied it back to a store. In addition, a remote object cannot modify or affect foreign data.
: The modes provided are:
LOCAL_OBJECT: Foreign data is sited locally within a store workspace. The data can be read and written by ML and foreign code.
: Pointer values are not restricted, that is, they can be simple indices (that is, relative values) or machine addresses.
REMOTE_OBJECT: Foreign data is sited remotely somewhere in the user's address space. The data can only be read by ML. It cannot be written by ML.
: Pointer values are restricted to machine addresses.

objectMode

Function

Signature: val objectMode : ('l_type) object -> object_mode
Description:
: This function returns the current object_mode.

object_status

Datatype

Specification:: datatype object_status = PERMANENT_OBJECT | TEMPORARY_OBJECT
Description:
: As foreign data is not stored directly as part of a foreign object, objects can be cheaply replicated without changing the meaning of the foreign data. However, it is also sometimes useful to be able to control the way in which foreign objects are replicated.
: To do this, each object is given a status value, which can be either permanent or temporary. The purpose of the object status is that permanent foreign objects can be duplicated but temporary objects are never duplicated and would be returned unmodified. Temporary objects are made by an operation that first duplicates a permanent object and changes the status of the duplicate to temporary.
: The functions which perform such duplication may need to take suitable care of the language-specific part of an object. As such, these function are provided as part of the language specific interfaces.
: The object status values are:
PERMANENT_OBJECT
: An object with permanent status usually represents some sort of 'live' object which is in some way persistent. By default, newly built objects are given permanent status.
TEMPORARY_OBJECT
: An object with temporary status usually represents an ephemeral (short-lived) object that is summoned into existence to perform a very specific role in a program.

objectStatus

Function

Signature:: val objectStatus : ('l_type) object -> object_status
Description:
: This function returns the current status of the given object.

OutOfBounds

Exception

Specification:: exception OutOfBounds
Description:
: This exception is raised if an attempt is made to 'move' or 'relocate' an object to some location outside the current store. It is analogous to the Subscript error that is raised upon an attempt to update an array at an invalid index.

Currency

Exception

Specification:: exception Currency
Description:
: This exception is raised upon an attempt to perform some action upon an object when the association between object and foreign data is assumed to be corrupt or invalid.
: The notion of data corruption or validity is naturally dependent upon the interpretation placed on the semantics of the data model of the language being interfaced with. In general, an object is assumed not current if it has just been moved, relocated or otherwise changed without its language-dependent interpretation (that is, its 'type') having been adjusted accordingly.

objectCurrency

Function

Signature:: val objectCurrency : ('l_type) object -> bool
Description:
: This predicate reports true if and only if the object supplied is assumed to represent current foreign data.

objectSize

Function

Signature:: val objectSize : ('l_type) object -> int
Description:
: This function returns the current size, in bytes, of the foreign data located in the store.

objectLocation

Function

Signature:: val objectLocation : ('l_type) object -> int
Description:
: This function returns the location of the associated foreign data in the store.

objectAddress

Function

Signature:: val objectAddress : ('l_type) object -> address
Description:
: This function returns the machine address of the location of the foreign data in the store.