CM3 includes many interfaces. Finding the right one for a particular task is not always easy. This index provides an overview of some of the most frequently used interfaces available in CM3. The interfaces can be loosely broken into the following categories:
There is also a complete alphabetical index.
Datatype Interface INTEGERInteger, Int32 BOOLEANBoolean CHARChar REFANYRefany REALRealType, Real LONGREALLongrealType, LongReal EXTENDEDExtended TEXTText
Text strings.
Strings are represented as values of type
TEXT. Text strings are immutable; they are
automatically garbage collected.
The TEXT type is used extensively throughout the Modula-3
libraries. The
Text interface
defines the basic operations on this type. Operations to convert
between other encodings of text strings are available in the
TextConv interface.
The internal representation of text strings is exposed in then
TextClass interface.
More specific interfaces for 8 bit (ISO charsets) and 16 bit (Unicode)
characters can be found in
Text8,
Text8Short,
Text8CString,
Text16, and
Text16Short.
The TextF interface from previous releases is no more supported.
ASCII characters.
ASCII includes constant
definitions for the character codes of non-printable characters, such
as ASCII.NL for new-line. It classifies characters into groups,
like digits or punctuation; each group is represented as a set
of characters. Finally, it provides mapping tables that translate
lower-case letters into upper-case and vice versa.
Machine Words and Bit Manipulation. The Word interface defines bit-level operations on machine words. The Swap interface is useful for writing code that must deal explicitly with byte ordering and/or word length issues.
Atoms. While not built-in types, atoms are handy for efficient comparison of text strings. The Atom interface describes the set of operations available for atoms.
Symbolic Expressions. The Sx interface provides symbolic expressions represented as a recursive linked-list structures, similar to those found in Lisp systems. It includes routines for reading and printing symbolic expressions, as well as some convenience procedures for manipulating them.
See also Formatting & I/O Conversions for interfaces that produce or parse text representations of the built-in types.
The CM3 libraries contain interfaces supporting the following data structures: linked lists, sorted linked lists, Lisp-like property lists, tables, sorted tables, sequences, priority queues, and sets.
Many of these data structures are available as generic interfaces. They can be instantiated with whatever types are needed. For most of the generic data structures, the libraries already include instances for text strings, integers, atoms, and arbitrary references. Many of the generics are packaged with makefile functions that make it simply a matter of writing a line in your makefile to instantiate them.
A generic implementation of singly-linked lists is available in the List interface and implementation. It includes predefined instances for atoms, integers, references, and text strings. The package includes makefile functions to create custom lists.
Lists may be sorted by using the generic ListSort interface and implementation. Like the List interfaces, there are predefined instances for atoms, integers, references, and text strings.
Property lists, simple linked lists of (name, value) pairs, are available from the Property interface. The related interfaces, PropertyV, MProperty, PropertyF, and MPropertyF provide more features.
A flexible and highly-reusable generic Table interface and implementation are available. Tables provide efficient mappings from values of one type to values of another. Like the list interfaces, the table interfaces are provided with predefined instances for the full cross product of the four basic types:
From \ To atoms integers references texts atoms AtomAtomTbl AtomIntTbl AtomRefTbl AtomTextTbl integers IntAtomTbl IntIntTbl IntRefTbl IntTextTbl references RefAtomTbl RefIntTbl RefRefTbl RefTextTbl texts TextAtomTbl TextIntTbl TextRefTbl TextTextTbl
Like the other generic data structures, predefined makefile functions are available to create custom tables.
Sorted tables are like tables with the added feature that it is possible to iterate through the elements of the table in a sorted order. The generic SortedTable interface and implementation are available. Like the other table interfaces, the sorted table interfaces are provided with predefined instances for the full cross product of the four basic types:
From \ To atoms integers references texts atoms SortedAtomAtomTbl SortedAtomIntTbl SortedAtomRefTbl SortedAtomTextTbl integers SortedIntAtomTbl SortedIntIntTbl SortedIntRefTbl SortedIntTextTbl references SortedRefAtomTbl SortedRefIntTbl SortedRefRefTbl SortedRefTextTbl texts SortedTextAtomTbl SortedTextIntTbl SortedTextRefTbl SortedTextTextTbl
Like the other generic data structures, predefined makefile functions are available to create custom sorted tables.
The Sequence interface and implementation provide generic extensible arrays. Elements can be added or removed from either end or directly indexed. The standard predefined instances for atoms, integers, references, and text strings are available.
The SequenceRep interface exposes the full details of the underlying representation of sequences. "Rep" is for "Representation". For maximum portability and implementation independence, programs should avoid using this interface. The standard predefined instances for atoms, integers, references, and text strings are available.
Predefined makefile functions are available to create custom sequences.
When it is necessary to access the underlying implementation, the PQueueRep interface defines the full details. For maximum portability and implementation independence, programs should avoid using this interface. The standard predefined instances for atoms, integers, references, and text strings are available.
Predefined makefile functions are available to create custom priority queues.
Kind \ Type integers texts references atoms Set IntSet TextSet RefSet AtomSet SetDef IntSetDef TextSetDef AtomSetDef SetList IntSetList TextSetList RefSetList AtomSetList
Predefined makefile functions are available to create custom sets.
See also the Atom interface, which provides a unique value for all equal text strings.
Sorted generic lists, tables, and arrays allow iteration in a sorted order.
Sorted Lists. The generic ListSort interface and its implementation add sorting to functions to those available in the List interface. As usual, there are instantiations AtomListSort, IntListSort, RefListSort, and TextListSort.
Sorted Tables. The generic SortedTable interface and its implementation allow you to build tables where you can iterate through their elements in a sorted order.
Sorted Arrays. The generic ArraySort interface and its implementation allow you to sort arrays. They are already instantiated as IntArraySort and TextArraySort.
Modula-3 provides a rich set of interfaces for mathematical and statistical programming. The Math interface provides access to the C math libraries. Many geometric abstractions are also available: Axis, Interval, Point, Rect, Transform, Path, Region, PolyRegion, and Trapezoid.
The generic
Sqrt interface and its
implementation
define a square root operation, instantiated as
RealSqrt and
LongSqrt for
REALs and LONGREALs, respectively.
The Stat
interface defines a set of tools for collecting elementary statistics
of a sequence of real-valued quantities.
The interfaces Random and RandomPerm provide random numbers and random permutations of numbers, respectively. RandomReal includes machine specific algorithms for generating random floating-point values.
Real, LongReal, and Extended are interfaces corresponding to the built-in floating-point types; their representations are available in RealRep and LongRealRep.
The interface FloatMode allows you to test the behavior of floating-point rounding and of numerical exceptions. On some platforms it also allows you to change the behavior, on a per-thread basis.
The interface FloatExtras, RealFloatExtras, and LongFloatExtras contain miscellaneous functions useful for floating point arithmetic. The generic interface Float and its instantiations RealFloat, LongFloat, and ExtendedFloat provide interfaces to floating-point arithmetic.
IEEESpecial
defines variables for the IEEE floating-point values
-infinity, +infinity,
and NaN (not a number) for each of the three
floating-point types.
The Env and Params interfaces provide access to the environment variables and command-line parameters given to a process when it is started.
See also the Process interface.
I/O Streams allow you to read and write streams of bytes to disks, network connections, other threads or processes, etc.
Basic Input and Output. The IO interface is a simple, high-level I/O interface. The Stdio interface declares the standard input, output, and error streams.
Input and Output Streams. The Rd interface defines input streams, known as "readers". The RdClass interface allows you to define new kinds of readers. UnsafeRd is an internal interface, providing non-serialized access to readers.
The Wr interface defines output streams, or "writers". The WrClass interface can be used to define new kinds of writers. UnsafeWr allows non-serialized access to a writer.
File Streams. FileRd and FileWr read from and write to files.
Text Streams.
TextRd and
TextWr read from and
write to TEXT strings.
They make it easy to apply string procedures
to streams or stream operations to strings.
Empty Streams. NullRd and NullWr represent empty streams.
Message Streams. MsgRd and MsgWr define message stream abstractions. A message is a sequence of bytes terminated by an end-of-message marker.
Stream Utilities. RdCopy copies bytes from readers to writers efficiently. AutoFlushWr automatically flushes its output in the background. RdUtils adds a few utilities for searching and manipulating readers.
Most formatting interfaces in CM3 work with strings, readers, and writers.
Fmt formats basic data types as strings. FmtTime converts times and dates to strings. FmtBuf is similar to Fmt, with the exception that it leaves its results in character buffers instead of TEXT strings. FmtBufF exposes some of the internal routines used by FmtBuf.
Scan converts strings back into basic datatypes. Lex provides lexical operations for reading tokens, parsing the basic datatypes, and matching and skipping blanks from a reader.
Formatter performs pretty-printing, the printing of structured objects with appropriate line breaks and indentation.
Convert converts between binary and ASCII representation of basic values. CConvert provides access to the lower-level conversion functions in C.
CM3 provides language-level support for multi-threaded applications. CM3's standard libraries and its runtime are multi-threaded. The Thread interface describes the basic portable interface for creating new threads (often called light-weight processes.) The interfaces Scheduler, ThreadF, and ThreadEvent provide access to the internal representation of threads and some control over the thread scheduler.
Network Objects. CM3's Network Objects system allows an object to be handed to another process in such a way that the process receiving the object can operate on it as if it were local. The holder of a remote object can invoke operations on that object just as if it had created the object locally. It can even pass the object to other processes.
NetObj is the basic interface for defining network objects. A few makefile commands make it easy to generate the code required to integrate network objects in your programs. The NetObjNotifier interface notifies a server if its clients die. And StubLib contains procedures to be used by stub code for invoking remote object methods and servicing remote invocations.
The current implementation of Network Objects uses TCP/IP as its transport layer. TCPNetObj provides the low-level hooks needed to implement network objects on TCP/IP. Network Objects are designed to make adaption to specialized network protocols easy.
Network Streams. Network Streams provide a set of high-level abstractions for sending and receiving messages across the network. ConnRW creates reader and writer streams from a connection; ConnMsgRW creates message streams from a connection.
TCP/IP Socket Interfaces. Using the TCP/IP interfaces, you can write safe, multi-threaded clients and servers for client/server computing. The same programs work whether you use Unix sockets or Windows winsock. The interface IP defines the addresses used for communicating with the internet protocol family. TCP provides bidirectional byte streams between IP sockets, implemented using standard Internet protocols. TCPSpecial is a lower-level utility interface for some TCP operations.
Databases, Persistent Storage. CM3 includes several facilities for saving data in persistent forms: Relational Databases, Pickles, Simple Snapshot Persistence, Stable Objects, and Bundles.
Relational Database Interface. The DB interface provides serialized access to relational databases. It allows multiple connections within one application and each may be used concurrently by multiple threads. An implementation based on Microsoft's ODBC is available for both Windows and Unix; a sample implementation for Postgres'95 on Unix is also included. You can modify the implementation to suit any relational database.
Pickles: Object Transcription (or "Serialization"). The Pickle interface provides operations for reading and writing arbitrary values as a streams of bytes. Writing a value as a pickle and then reading it back produces a value equivalent to the original value. You can write pickles for values that have cyclic references (such as doubly-linked lists), or that are arbitrary graph structures. The process preserves the values, shapes (ie. internal pointers) and sharing (ie. multiple pointers to a single value) of the original values.
Two implementations of the Pickle interface are available. Pickle2 is an implementation geared toward heterogeneous platforms; it works across platforms, reconciling machine word encoding, little-endian, big-endian and size differences. Pickle is a more efficient implementation for homogeneous setups. Pickles are used by Network Objects for transferring objects across processes.
SmallDB: Simple Snapshot Persistence. SmallDB stores objects in a file in a recoverable fashion. If a crash occurs while the objects are being written to disk, their state can be restored from the latest consistent snapshot the next time they are used. For binary snapshots, use the combination of SmallDB and Pickle.
Stable Objects. Stable Objects extends the lightweight object storage provided by Pickles and SmallDB to allow for recoverable storage of objects via logging and check-pointing. Updates to objects are logged to stable storage automatically. When the state of an object is restored from disk, the restoration process checks to see if a crash occurred before the entire state of the object was written to disk. If so, the state of the object is recovered from the log of modifications to the object.
The generic interface Stable defines a subtype of a given object type that is just like that object type, but stable. Makefile operations are provided to create stable versions of arbitrary object types. LogManager manages readers and writers for the log and checkpoint files used by stable objects. StableRep defines the representation of stable objects. Log provides debugging operations for the log. StableLog contains procedures for reading and writing logs for stable objects. StableError defines the various error scenarios and corresponding exceptions.
Bundles. Bundles package arbitrary files at compile-time so that their contents can be retrieved by a program at run-time without accessing the file system. The Bundle interface allows runtime access to the stored data. BundleRep exposes the representation of bundles. You can bundle files with your programs by using the provided makefile functions.
CM3 provides a set of high-level, portable interfaces to the underlying OS facilities such as files, processes, directories, terminals, and keyboards. The interfaces to these operating system functions are identical whether you are running on Windows or Unix.
File-system Interfaces. The File interface defines a type that can be a source or sink of bytes. File handles provide an operating-system independent way to perform raw I/O. For buffered I/O, use the FileRd and FileWr interfaces.
Pathname defines procedures for manipulating pathnames in a portable fashion. The FS interface provides access to persistent storage (files) and naming (directories).
RegularFile defines regular file handles which provide access to persistent extensible sequence of bytes, usually disks. A Terminal handle is a file handle that provides access to a duplex communication channel usually connected to a user terminal.
TempFiles creates temporary files which get deleted automatically upon termination of the process.
Processes, Pipes, O/S Errors. The Process interface manages operating-system processes (e.g., creating processes and awaiting their exit). A Pipe is a file handle that can be used to communicate between a parent and a child process or two sibling processes.
OSError defines the exception raised by many of the operating system interfaces.
Time, Date, Ticks. Time defines a moment in time, reckoned as the number of seconds since some epoch or starting point. Date defines a moment in time, expressed according to the standard (Gregorian) calendar, as observed in some time zone. Tick defines a value of a clock with sub-second resolution, typically one sixtieth of a second or smaller.
Timestamps, Capabilities, Fingerprints.
Timestamps provided by the
TimeStamp
interface
are totally ordered in a relation that approximates the real
time when the value was generated. If two timestamps are
generated in the same process then the ordering of the
timestamps is consistent with the order that TimeStamp.New
was called.
The Capability
interface defines unique global identifiers that are extremely difficult for
an adversary to guess.
The Fingerprint
interface allows efficient comparison of large strings, and
more general data structures such as graphs.
MachineID
returns a unique number for the machine running the Modula-3 program.
Platform-Specific Interfaces. Not all programs are portable. CM3 allows access to lower-level interfaces available from the host operating system. Most of these interfaces are unsafe.
Microsoft Windows. The Windows releases of CM3 include interfaces for accessing many of the calls from the Win32 API:
WinBaseTypes, WinDef, WinError, WinNT, WinBase, WinCon, WinGDI, WinIoctl, WinNetwk, WinReg, WinSock, WinUser, WinVer, NB30, CDErr, CommDlg, TlHelp32.
Intermediate interfaces that provide access to the middle layers of the Modula-3 libraries are also available on Win32 platforms:
FileWin32, TimeWin32, OSWin32, TCPWin32, OSErrorWin32.
Unix. The Unix releases of CM3 include interfaces for accessing many of the calls from common Unix APIs:
Udir, Uipc, Uprocess, Usignal, Uugid, Uerror, Umman, Upwd, Usocket, Uuio, Uexec, Umsg, Uresource, Ustat, Uutmp, Ugrp, Unetdb, Usem, Utime, Uin, Unix, Ushm, Utypes.
Intermediate interfaces that provide access to the middle layers of the Modula-3 libraries are also available on Unix platforms:
FilePosix, TimePosix, OSConfig, TCPPosix, OSErrorPosix.
Several standard C libraries are available from CM3. Cerrno, Cstddef, Cstdlib, Ctypes, Cstdarg, Csetjmp, Csetjmp, Cstdio, and Cstring are Modula-3 interfaces for standard C libraries. M3toC converts between C strings and Modula-3 TEXT types.
Several run-time interfaces provide low-level access to the Modula-3 run-time:
Allocator RTAllocator, RTAllocStats. Heap Management RTHeap, RTHeapDep, RTHeapInfo, RTHeapMap,
RTHeapRep, RTHeapDebug, RTHeapStats, RTHeapEvent.Garbage Collector RTCollector, RTCollectorSRC. Type Management RTTipe, RTType, RTMapOp, RTTypeFP,
RTTypeMap, RTutils, RTTypeSRC.Code and Execution RTLinker, RTProcedureSRC, RTModule,
RTProcedure, RTException.System Interface RTParams, RTArgs, RTProcess RTSignal,
RTStack, RTMachine.Low-level RTHooks, RT0. Miscellaneous RTIO, RTPacking, RTMisc.
Main interface. The Main interface is the entry point for executable programs. All programs must include a module that exports this interface.
Weak References. Using the WeakRef interface, you can register cleanup procedures to be run when the garbage collector is about to collect an object.
Performance Tuning. ETimer keeps track of elapsed time. It can be used for performance measurements. PerfTool and LowPerfTool control access to performance monitoring tools.
Configuration. The M3Config interface exports the configuration constants defined when the system was built.
There are many more Modula-3 interfaces than are described in this index. You can continue learning about Modula-3 interfaces by browsing the list of interfaces available in your CM3 system.
Good Luck!