User manual | Ansa Reference Manual Part 11B - Computer Conservation Society

Part XI
Chapter 11
Internal
Functions
The following manual pages describe the C language interfaces for those
functions internal to the ANSA support environment.
None of the routines
in this section should be called directly by application programs. Calls to the
top level routines are generated by the preprocessor and stub generator.
All application
programs
should be compiled with the switch:
-I/usr/local/include
and then linked with:
/usr/local/lib/libansa.a
All the
definitions
needed
by the
stubs are collected
together
in
included by all stubs. Header files for
ANSA service interfaces should be kept in /usr/local/include/ansa so that
they can also be picked up by the standard -1 switch.
<ansa/ansa. h> which is automatically
Internal
modules should be compiled with the switch:
-I/usr/local/include/ansa/capsule
and should include the header file "capsule. h". Modules using
internal routines may need additional
include files as specified
individual manual pages.
Please note that your installation
may have
libraries somewhere other than /usr/local.
put the include
certain
in the
files
and
All interface types defined in <ansa/ansa. h> have a prefix of ansa_, in order
to avoid name clashes with application code. Within the interpreter
this is
not necessary and the equivalent
internal
types without the prefix are
defined in the file “standard. h" which is included by "capsule. h".
The interface synopsis for each routine in the following manual pages is in
the proposed ANSI C standard format using function prototypes.
However,
in order to maximize portability,
the source as issued does not yet use
function prototypes.
ARM XI, II/ 1 (Release 01.00)
Internal
Functions
ANSA Reference
Manual
BINDER(X1)
NAME
Binder - binds capsules together
via their external
interfaces
PURPOSE
The binder acts as a local agent for the trader; enabling
server
capsules to advertise interfaces
(via the trader) and create the
communications
socket necessary
to accept invocations
of the
interface operations.
The binder also enables client capsules to
locate server capsules supporting
a particular
interface
(via the
trader) and to create the communications
plug and channel
necessary to invoke the interface operations.
SYNOPSIS
#include
<ansa/ansa.h>
#include
"binder.h"
ansa_Status
binder-export
(InterfaceRef
String
String
String
Cardinal
InterfaceId
Dispatch
InterfaceRef
*trref,
context,
instance,
concurrency,
id,
*dispatcher,
*ifref) ;
type9
ansa_Status
binder - withdraw
(InterfaceRef
InterfaceRef
*trref,
*ifref)
ansa_Status
binder-import
(InterfaceRef
String
String
String
InterfaceRef
*trref,
type,
context,
constraints,
*ifref) ;
*ifref)
;
;
ansa - Status binder - discard
(InterfaceRef
void
binder-terminate
(void)
ansa_Status
binder_bindRef
(InterfaceRef
ansa_ChannelId
*ifref,
*plugPtr)
ansa_Status
binder_bindSvc
(Cardinal
InterfaceId
Dispatch
InterfaceRef
ansa_ChannelId
concurrency,
ifid,
*dispatcher
*ifref,
*plugPtr) ;
ARM X1,11/
2
;
(Release 01.01)
;
Internal
Functions
ANSA Reference Manual
BINDER(X1)
DESCRIPTION
The binder-export function calls the nucleus to make a new socket
with the specified concurrency and dispatch routine. If a particular
(non-zero) socket is specified the binder will attempt to allocate it;
otherwise a suitable one will be chosen and its identity returned. It
then calls the trader to register the export and stores the details of
the export instance
for use by binder-withdraw
and
binder-terminate.
The binder-withdraw
function cancels a preceding export by
requesting the trader to delete the relevant export entry and
requesting the nucleus to withdraw the socket.
The bindeyzmport
function calls the trader to lookup the interface
and then calls the nucleus to make a plug for the server capsule’s
socket. If a particular (non-zero) plug is specified the binder will
attempt to allocate it; otherwise a suitable one will be chosen and its
identity returned.
The binder-discard
function cancels a preceding
requesting the nulceus to discard the plug.
The binder-terminate
done by the capsule.
import
by
function withdraws all outstanding exports
The binder_bindRef
and binder_bindSuc
functions do the actual
work for binder import and binder export, respectively. They have
been broken out-to permit access from client stubs.
FILES
ERRORS
SEE ALSO
TRADER (X), Support Environment (X1, NUCLEUS (XI).
USAGE
The
binder-export,
bznder_withdraw,
binder-import,
binder-discard
and brnder_termznate functions calls are generated
by the preprocessor. The bznder terminate function is also called by
the system module after receiving a termination signal from the
operating system.
ARM X1,11/ 3 (Release 01.01)
Internal
Functions
ANSA
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
1104188
16!12/88
Reference
Changes
Pages
Release
Version
1.0
Version
2.0
BINDER(X1)
Manual
initial release
stackSi ze argument moved from
binder
export to nucleus_tasks
buf fer?i ze argument from
bmder
export calculated
dynamically
concurFency argument added to
binder-export
argument types made consistent
with
<ansa/ansa.h>
multiple protocol support added
lOi4/89
Version
2.5
InterfaceId support added
bindRef and bindSvc routines
ARM XI,1 l/ 4 (Release
01.01)
provided
Internal
ANSA
Functions
Reference
BUFFER(X1)
Manual
NAME
Buffer - interpreter buffer management
PURPOSE
Provides buffer management functions for capsule message buffers.
These buffers are used by client and server stubs to marshal and
unmarshal the arguments or results of invocations.
SYNOPSIS
#include <ansa/ansa.h>
/* or "capsu1e.h" */
#include "buffer.h"
void
buffer_init (Cardinal header,
Cardinal data,
Cardinal trailer) ;
ansa_BufferLink buffer-make
(Cardinal bytes)
void
buffer-free
(ansa_BufferLink descriptor)
void
buffer-reset (ansa_BufferLink descriptor)
void
buffer-swap
;
(ansa_BufferLink old,
ansa_BufferLink new)
;
;
;
DESCRIPTION
Buffers are constructed from a linked list of one or more buffer
segments. A buffer segment is a contiguous area of memory
containing all or part of a message. Each buffer segment has an
associated control block called a buffer descriptor; this contains the
base address and size of the buffer segment, plus the base address
and size of that section of the segment which contains valid data.
Buffer descriptors need not be contiguous with their associated
buffer segment and may be linked together to form a buffer list.
The format of a buffer descriptor and a buffer link are defined in the
file <ansa/ansa.h> includedby "capsu1e.h".
typedef struct ansa_buffer_descriptor *ansa_BufferLink
typedef struct ansa_buffer_descriptor
I
ansa BufferLink link
unsigned long
type
unsigned long *base
unsigned long
size
char
*data
unsigned long
used
;
;
;
;
;
;
/*
/*
/*
/*
/*
/*
;
NULL = end of buffer list
unused
word aligned segment address
number of bytes in segment
byte address of used section
number of bytes used
I
ansa_BufferDescriptor;
ARM X1,11/ 5 (Release 01.00)
*/
Internal
Functions
Reference
ANSA
Manual
BUFFER(X1)
The buffer-hit
function
is called by each communications
protocol
stack as part of its startup
sequence.
Buffer_init accumulates
the
maximum
header, data and trailer sizes in order to calculate
the
size of a standard
buffer
and leave enough
room for the largest
header and trailer in ail buffers.
The buffer-make
function
allocates,
and returns
a pointer
to, a
single
buffer descriptor
with an attached
data segment
of at least
the requested
number
of bytes plus the largest
header
and trailer
used by the communication
protocols
loaded in the capsule.
The
buffer is initialized
with a used data section of zero bytes starting
If insufficient
memory
was
after
the largest
buffer
header.
available
to allocate
the buffer.
a NULL pointer
is returned.
If a
buffer
length
of zero bytes is requested
then a standard
buffer,
which will hold an unfragmented
message
for any loaded protocol, is
supplied.
The buff er f ree f unction
are linked to it).
disposes
of a buffer
(and
any
buffers
The buffer-reset
function
re-initializes
the buffer
by setting
fields
of the first
buffer’s
descriptor
to the values
used
buffer_mahe and freeing any linked buffers.
that
the
by
The buffer_swap function
exchanges
the buffer segments
attached
to the old and new buffer descriptors
and frees the new buffer, which
now consists
of the new descriptor
and the old segment,
leaving
the
new segment
attached
to the old descriptor.
FILES
SEE: ALSO
INSTRUCT
(XI).
CSAGE:
The buffer management
protocols
and automatically
FL’I’UKK
routines
are
generated
used by the communications
stubs.
DIHEC'I'IONS
Linked
buffer
support
may
be added
ARM X1,11/ 6 (Release
to rex and the stub
01.00)
generator.
Internal
Functions
BUFFER(X1)
ANSA Reference Manual
CHANGE HISTORY
Date
Release
j
Pages 1
Changes
l/04/88
Version 1.0
initial release
16/12/88
Version 2.0
function names changed according to
module naming conventions
argument types made consistent with
<ansa/ansa.h>
buffer segment functions replaced by
buffer swap
buffeyinit
function added
ARM XI,1 I/ 7 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
CHANNEL(X1)
NAME
Channel
PURPOSE
Manages
updating
- binds plugs to sockets
the capsule’s
channel
table, enabling
the creation,
and deletion of entries for both plugs and sockets.
SYNOPSIS
#include
"capsu1e.h"
#include
"channe1.h"
void
channel_init
(void)
void
channel-select
(Channel Id
index)
Status
channel_selectType
(ChannelId
ChannelType
index,
We)
Status
channel - make
(Channel Id
index)
Status
channel
(Cardinal
Dispatch
Status
channel-plug
socket
;
(void)
void
channel-increment
(void)
;
;
void
channel-free
(void)
;
void
channel-cleanup
(void)
;
;
;
concurrency,
*dispatcher)
(Protocol Id
Endpoint
Boolean channel-decrement
;
protocol,
destination)
;
;
The channel_imt
function creates and initializes the channel table
with the dummy (zero) entry and one free channel.
The dummy
entry is used by channeZ_make to initialize new channels.
The channel_seZect function makes the specified channel table entry
the current one by setting the global variables channel Index to its
index and channelptr to its address.
The channei_selectType
function makes the specified channel the
current one only if it is the correct type. The type DUPLEX is
equivalenttoPLUG
or SOCKET.
channei_make
function finds, initializes
and selects a free
channel, extending the channel table if necessary.
If index is nonzero then that particular channe! is selected; otherwise the first free
channel is selected.
The
ARM XI,1 1, 8 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
CHANNEL(X1)
The channeZ_socket function fills in the currently selected channel
as a socket.
The concurrency argument
limits the number of
invocations which may be active on the socket; when this limit is
reached additional invocations are ignored until one of the current
invocations completes. When an invocation which would not exceed
the concurrency is received, then the dispatcher function is called.
The channeZ_pZug function fills in the currently selected channel as
a plug, which is bound via the specified protocol to the capsule and
socket specified in the destination argument.
The channel-decrement
function checks if the concurrency limit has
been reached for the current channel; if so it just returns FALSE,
otherwise it decrements the available concurrency and returns TRUE.
The channel-increment
concurrency of the current
function
channel.
increments
The channelfree
function frees the current channel
disconnects all the sessions which are using it.
The channel-cleanup
function
disconnects all of its sessions.
frees all the capsules’s
the
available.
for re-use and
channels
and
FILES
EKRORS
SEE ALSO
INSTRUCT
(XI), NUCLEUS
(XI), SESSION (XI).
USAGE
Channel
init is called by the main program in the nucleus during
capsuleinitialization.
Channel-make,
channel-socket
and
channelqlug
are only called by nucZeus_socket and nucleusglug.
Channel-select
and channeZ_seZectType
are called by nucleus,
schedule and session.
Channel-decrement
and channel-increment
are only called by schedule
before and after dispatching
an
invocation.
Channelf
ree is only called by nucleus-withdraw
and
nucleus - discard.
Channel
cleanup is only called by the Terminate
and Abort instructions during capsule termination.
ARM XI,1 l/ 9 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
CHANNEL(X1)
~YJIIHWrmuwrrorvs
Export
stamps
will be added.
CHANGEHISTORY
Date
1~04,‘88
16’12:‘88
Release
1 Version
/ Version
Changes
Pages
1.0
1
2.o /
ARM XI,lli
I initial
release
Completely
redesigned
as an internal
module with all external
interfaces
/ provided
by the nucleus.
10 (Release
01.001
Internal
Functions
ANSA
Reference
ECS(XI)
Manual
NAME
ECS
- synchronization support with eventcounts and sequencers.
PURPOSE
Provides primitives for controlling the relative
concurrent thread execution within a capsule.
ordering
SYNOPSIS
#include
#include
"capsu1e.h"
"ecs.h"
typedef struct
Counter
ThreadId
) ECRec ;
ecrec {
tag
que
typedef struct
Counter
) SqRec ;
tag
;
;
sqrec {
;
typedef
ECRec
*EventCount
;
typedef
SqRec
*Sequencer
;
EventCount
ecs_makeEventCount
(Cardinal
iv)
;
Status
ecs_freeEventCount
(EventCount ec)
;
Counter
ecs- read
(EventCount ec)
;
void
ecs- await
(EventCount ec
Counter
v)
,
;
void
ecs_advance
(EventCount ec)
;
Sequencer
ecs_makeSequencer
(Cardinal
iv)
;
Status
ecs_freeSequencer
(Sequencer
sq)
;
Counter
ecs- ticket
(Sequencer
sq)
;
Counter
ecs- castcounter
(Cardinal
c)
;
#define ecs_makeEventCountO ecs_makeEventCount ((Cardinal)O)
#define ecs_makeSequencerO
ecs_makeSequencer
ARM X1,11/ 11 (Release 01.01)
((Cardinal)O)
of
Internal
Functions
ANSA
Reference
Manual
ECS(X1)
The ecs makeEoentCount
function allocates and returns a pointer
of type LentCount to an ECRec record. The tag field is initialized to
the value of iv, and que is set to the dummy (zero) ThreadId. If
insufficient
memory is available
to allocate the record, a NULL
pointer is returned.
The subsidiary
definition
ecs_makeEuentCountO
operates
identically, except that the tag value is initialized to zero.
The ecsfreeEuentCount
function disposes of an eventcount if its
associated queue is empty and returns ok, otherwise resourceInUse
is returned.
The ecs_read
ec.
function
returns
the current
value of the eventcount
The ecs - await function suspends the calling thread if the value of
the eventcount ec is less than the parameter v. Threads are set into
the WAITING state and placed onto a queue associated
with the
eventcount prior to scheduler-r ! being called.
The ecs advance function increments
the current value of the
eventcount
ec by one and reawakens
one or more threads on the
associated queue which are awaiting the value just attained.
The ecs_makeSequencer
function allocates and returns a pointer of
type Sequencer to an SqRec record. The tag field is initialized to the
value of iv. If insufficient
memory is available
to allocate the
record, a NULL pointer is returned.
The subsidiary
definition
ecs_makeSequencerO
operates
identically. except that the tag value is initialized to zero.
The ec:;_f we S e q uencer function
disposes of a sequencer
and returns
ok.
The ecs - ticket function returns the current
sq and increments
its value by one.
The ecs_castC’ounter
function returns
type CardinalcasttotypeCounter.
value of the sequencer
the value of its argument
ARM X1,11< 12 (Release 01.01)
of
Internal
Functions
ANSA Reference Manual
ECS(X1)
ERRORS
SEE ALSO
SCHEDULE (XI), THREAD (XI).
USAGE
These synchronization primitives are to be used in generated stubs
to provide support for declarative path expression interface
constraints.
FUTURE
DIRECTIONS
This design is predicated on the use of non-preemptive scheduling
and relies on mutual exclusion guarantees given by the current
single processor environments of the testbench. Ports to multiprocessor machine environments will require explicit low-level
mutual exclusion mechanisms.
CHANGE
Date
HISTORY
Release
Pages
813189 Version 2.5
Changes
initial release
ARM X1,11/ 13 (Release 01.01)
Internal
Functions
ANSA Reference Manual
IDCACHE(X1)
NAME
Idcache
- cache of InterfaceId
to plug mappings
PURPOSE
These routines maintain a cache of InterfaceId to plug mappings.
Entries are made to the cache whenever an interface is imported or
if a remote invocation is made on an InterfaceRef
which does not
have an entry in the cache.
In actual fact, the cache is indexed by InterfaceId
and operation
number; such a structure
permits multiple
plugs per imported
interface.
situations
Future releases may provide additional
made in the cache.
are
SYNOPSIS
#include
<ansa/ansa.h>
#include
"idcache.h"
/* or "capsu1e.h"
*/
void
idcache_init
(void)
int
idcache_add
(InterfaceId
Cardinal
ansa_ChannelId
%j
;
id,
void
idcache - de1
(InterfaceId
id)
ansa_ChannelId
idcache_map
(InterfaceId
Cardinal
op)
;
;
id,
;
DESCRIPTION
idcache - ini t() initializes
initialization.
the cache, and is invoked during
capsule
idcache - add() adds an entry
to the cache corresponding
to the
specified InterfaceId and operation number.
If an entry currently
exists for that (InterfaceId,
op) pair, all entries corresponding
to
that particular InterfaceId are purged from the cache before making
the addition.
idcache de1 () purges
specified InterfaceId.
all entries
in the cache corresponding
to the
idcache - map0 scans the cache for the entry corresponding
to the
If successful,
the
specified InterfaceId
and operation
number.
corresponding
channel is returned as the value of the function: if not
in the cache, the value (ansa_Channel Id)0 is returned.
ARM X1,11/
14
(Release
01.011
Internal
Functions
ANSA Reference Manual
IDCACHE(X1)
FILES
ERRORS
SEE ALSO
USAGE
All uses of these routines in release 2.5 specify an operation
Oin idcache_add() and idcache_map()calls.
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
10/4/89
Release
Version
Pages
2.5
Changes
initial release
ARM X1,11/ 15 (Release
01.01)
number
Internal
Functions
ANSA Reference Manual
INSTRUCT(X1)
NAME
Instruct
- executes the interpreter instructions
PURPOSE
Provides (or re-packages)
those instructions
required by ANSA
capsules but not provided by the host processor or operating system.
The distinction
between
instructions
and operations
is that
instructions
perform those functions that must be provided by the
local capsule infrastructure
and cannot be provided by separate
capsules. Instructions are not usually referenced directly by source
programs, but are executed by compiled or generated code.
On an ANSA processor,
hardware or microcode.
be the system calIs.
these instructions would be implemented in
In an ANSA operating system they would
SYNOPSIS
#include
<ansa/ansa.h>
#include
"instruct.h"
/* or "capsu1e.h"
*/
ansa - Status
Call
(ansa_ChannelId
ansa_BufferLink
plug9
buffer)
;
ansa_Status
Cast
(ansa_ChanneId
ansa_BufferLink
plug,
buffer)
;
ansa_SessionId
Request
(ansa_ChannelId
ansa_BufferLink
plug,
buffer)
;
ansa - Status
Collect
(ansa_ SessionId
ansa_Threadld
Spawn
(Dispatch
ansa_BufferLink
*dispatcher,
buffer) ;
ansa ThreadId
Fork
(Dispatch
ansa_BufferLink
*dispatcher,
buffer) ;
ansa - Status
Join
(ansa- ThreadId
ansa - ThreadId
Thread
(void)
void
Pause
(void)
void
Terminate
(String
int
message,
reason)
;
void
Abort
(String
ansa - Status
module,
reason)
;
(ansa_ChannelId
ansa_BufferLink
socket,
buffer)
;
typedef
void
(Dispatch)
promise)
child)
;
;
;
;
,ZRM X1.11: 16 (Release
01.00)
Internal
Functions
ANSA Reference Manual
INSTRUCT(X1)
DESCRIPTION
The Call instruction transmits the request buffer to the capsule
bound to the other end of the channel referenced by the plug. The
calling thread is blocked until the corresponding response buffer is
received. The request and response buffers both use the same buffer
descriptor but the response buffer may have a different buffer
segment.
The Cast instruction
transmits the request buffer to the capsule
bound to the other end of the channel referenced by the plug. The
calling thread is only blocked until the request buffer has been
processed.
The Request instruction transmits the request buffer to the capsule
bound to the other end of the channel referenced by the plug. The
calling thread is only blocked until the request buffer has been
processed.
A promise is returned which may later be used by the
calling thread in a Collect instruction, which will block until the
associated response is available.
The request and response buffers
both use the same buffer descriptor but the response buffer may
Promises may be collected in any
have a different buffer segment.
order.
The Spawn instruction
creates a child thread,
which may be
processed concurrently, and which the parent thread never intends
to Join. The spawned thread will execute the dispatcher
function
and unmarshall
its arguments
from the buffer. When the
dispatcher exits the spawned thread will terminate and the buffer
will be freed.
The Fork instruction creates a child thread, which may be executed
concurrently, and which the parent thread subsequently
intends to
Jam in order to obtain its results. The forked thread will execute
the dispatcher function and unmarshall its arguments from, and
marshal1 its results into, the buffer. When the dispatcher exits,the
forked thread will block until its parent joins with it and then
terminate. The Fork instruction returns the thread identifier of the
child thread which may be used by the parent thread in a Join
instruction, which will block until the child thread has finished
executing and its response buffer is available.
The request and
response buffers both use the same buffer descriptor
but the
response buffer may have a different buffer segment.
ARM X1,11/ 17 (Release 01.00)
Internal
Functions
ANSA Reference Manual
The Thread instruction
thread.
returns
the thread
INSTRUCT(XD
identifier
of the calling
The Pause instruction
polls for incoming messages and schedules
the calling task (and thread) on the end of the queue of tasks
waiting to run.
The Terminate instruction
outputs a message on stderr of the
format:
:: capsule <id> terminated: <message> #<reason>
if the message argument is not NULL. It then performs the capsule
cleanup operations and exits with reason as the status code.
The Abort instruction
<module>
outputs a message on stderr of the format:
:: capsule <id> aborted: status <reason>: <text>
where the text string describes the reason. If reason is a system
error, it outputs a second line describing the system error. It then
performs the capsule cleanup operations and exits with reason as
the status code.
The Dispatch instruction is an up-call used by the interpreter to call
a dispatch procedure to service incoming invocations.
Outgoing
response messages to incoming calls must use the same buffer
descriptor as the incoming request, but the buffer segment may be
changed.
The outgoing response to a call is transmitted
when the
dispatch function exits. Responses are not sent for casts.
FILES
ERRORS
SEE ALSO
Support Environment(X),
BUFFER
(XI), NUCLEUS
(XI),
USAGE
Before a Call. Cast or Request instruction
can be executed, a plug
must be created by nucleusglug.
Calls and casts performed by the
same thread on the same plug are sequence preserving.
Requests
are not sequenced.
Forked and spawned threads may be serialized if insufficient tasks
are provided (see nucleu.s_tashs) for their concurrent execution.
In
particular, forked threads will be executed on their parent thread’s
ARM XT,11'18 (Release01.003
Internal
Functions
ANSA Reference Manual
INSTRUCT(X1)
task if they have not been assigned a task by the time their parent
executes the Join for them; and spawned threads may never be
executed if there are no free tasks and none of the existing threads
terminate.
Scheduling between threads (and the tasks executing them) is non
pre-emptive. The Pause instruction should be used in long compute
bound loops to allow the capsule to receive incoming messages and
service the other tasks.
Before a Dispatch instruction can be executed by the interpreter a
socket must have been created for it by nucZeus_socket.
The Abort instruction should only be executed by the internal
modules and, except for Pause, all other instructions should only be
executed by code generated by the preproccessor or stub generator.
FUTURE DIRECTIONS
Support for object groups will be added.
CHANGE HISTORY
Date
Release
Changes
Pages
l/04/88
Version 1.0
initial release
16/12/88
Version 2.0
argument types made consistent with
<ansa/ansa.h>
non-blocking calls (Request and
CoZZect) added
multi-threading (Spawn, Fork, Join,
Thread and Pause) added
status code argument added to
Terminate
ARM X1,11/ 19 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
MPS TABLE(X1)
NAME
MPS - a generic interface
PI
for message passing services
KPOSE
Provides a standard interface between protocols such as REX and
GEX and locally available
message passing services.
A map
indicates which MPSs are loaded (aka the protocol stack). Each map
entry contains the address of a table containing the entry points for
each of the required MPS functions.
SYNOPSIS
#include
"capsu1e.h"
#include
"protoco1.h"
typedef
struct
c
Status
(*mpsStartup)
(CapsuleAdr *self,
Status
(*mpsSendMsg)
(char
Cardinal
Cardinal
Cardinal
*pkt,
psize,
CapsuleAdr
*remcap);
(*mpsReceiveMsg)(char
void
(*mpsTick)
void
(*MpsCleanup)
Cardinal maxSendUnit
*extra);
Cardinal
*pkt,
psize,
CapsuleAdr
*remcap);
(void);
(void);
;
Cardinal maxReceiveUnit
;
MpsTable;
MpsTable
*mpsMap[]
;
DESCRIPTION
mpsStartup initializes
the message passing service.
It is called
during capsule initialization,
it’s principal function is to ensure that
the MPS is functional
and to acquire a unique address for this
capsuleiMPS
combination.
The port number may be specified in
self. Any necessary
local resources (e.g. sockets under BSD style
networking) are also allocated.
On successful
initialization
two result values are provided, self
holds the capsule address used by this 3IPS and extra is set to the
number of bytes of header information
which this YIPS requires.
ARkI X1,11/
20 (ReleaseOl.Ol!
Internal
Functions
ANSA Reference Manual
MIPS TABLE(X1)
The port number is notified to the interpreter via the protocol_open
operation.
The two message transfer routines take a pointer to a REX packet
buffer (pkt)and a pointer to a capsule address structure (remcap) as
par ameters.
Each also takes a buffer size parameter, for
mpsSendMsg
psize is the number of bytes to transmit,
for
mpsReceiueMsg
it is the maximum size of the buffer. The current
design relies upon REX to provide retry mechanisms to overcome
transient errors and so any error codes which are signalled should
reflect serious MPS failures.
mpsSendMsg attempts to send psize bytes of REX header and data
to the nominated capsule and host., Returns transmitfailureor ok.
mpsReceiveMsg
attempts to receive data waiting for this capsule
and returns the number of bytes received (0 means there wasn’t
any) and the capsule address of the source. If the data available
exceeds psize only the first psize bytes are copied into pkt, no
indication is given that this has happened and the MPS quietly
discards the excess.
mpsTick is called at irregular intervals to enable time related
activities to be scheduled, the minimum inter-tick period is
guaranteed by the interpreter.
mpsCZeanup is called to allow the MPS to do any necessary
housekeeping before the capsule is shutdown.
The values of maxSendUnit and maxReceiueUnit are used by Rex to
determine how to fragment a message too large for a particular
MPS.
FtLES
EKROKS
SEE ALSO
MPSUDP(XI), MPSTCP(XI), PROTOCOL (XI), REX (XI).
ARM X1,11/ 21 (Release 01.01)
Internal
Functions
ANSA
Reference
MPS TABLE(X1)
Manual
USAGE
The functions for a particular MPS are called by an expression
form:
(*mpsMap[protocolIndex]->mpsTick)()
FUTUKE
of the
DIRECTIONS
This MPS interface has been developed on the socket interface to the
UDP/IP and TCP/IP protocols on various machines, other protocols
and different networking styles streams are being considered so as
to validate the general approach as well as the incorporation
of
Error signalling.
CHANGE
Date
HISTOKY
Changes
Pages
Release
l/04/88
Version
1.0
designed
by E. Oskiewicz
16i12/88
Version
2.0
designed
by D. Oliver and E. Oskiewicz
10/4/89
Version
2.5
addition of maxUnit
Table entry
ARM XI,1 I/ 22 (Release 01.01)
fields to MPS
In tern al
Functions
ANSA Reference
Manual
MPSIPC(XI)
NAME
MPSIPC - a message passing service interface to UNIX system V
named pipes.
PURPOSE
Implements the standard MPS interface between protocols such as
REX and GEX and UNIX system V named pipes. This provides
optimized transport for inter-capsule traffic when the capsules are
on the same UNIX host system.
SYNOPSIS
#include "capsu1e.h"
#include "protoco1.h"
Status
MPS_startup
(CapsuleAdr *locp,
Cardinal
*extra);
Status
MPS_send
(char
*bufp,
dlen,
Cardinal
CapsuleAdr *remp);
Cardinal
MPS_receive
(char
*bufp,
bmax,
Cardinal
CapsuleAdr *remp);
void
MPS_decay
(void);
void
MPS_cleanup
(void);
DESCRIPTION
initializes the IPC message passing service, tries to
create a named pipe in the /usr/tmp directory, and opens a file
descriptor to the named pipe. If successful, protocoZ_open
is called
with the pin id equivalent to this file descriptor.
MPS_startup
The named pipe is given the name ansa.%d, where the %d is replaced
by a formatted decimal number. If the port component of the
capsule address locp is non-zero that value is used, otherwise the
process id of the capsule is used. The remainder of locp is set to the
ASCII hostname.
On return, locp contains the complete capsule address and extra is
the size of the extra header required by this MPS for message
encapsulation (4 bytes).
ARM X1,11/ 23 (Release 01.00)
In ternal
Functions
ANSA Reference Manual
MPSIPC(X1)
MPS_send
attempts to send dlen bytes of data in bufp via the
named pipe associated with the destination capsule remp. It always
returns ok, relying upon protocols such as REX or GEX above to
handle failures.
MPS_receiue
performs a two-part read from the named pipe. First
the MPSIPC header is read to determine
the remote capsule’s
process id, which is placed in remp, and the length of the message.
The message is then read into buf p and the number of bytes received
returned.
If the message length exceeds bmax the capsule is
terminated,
as this is a heinous protocol error.
MPS_decay
housekeeping
is a null operation
requirements.
as MPSIPC
has
MPS_cleanup
no relevant
is called just before the capsule expires to permit the
removal of the named pipe from /u sr/ tmp.
FILES
ERRORS
SEE ALSO
MPS TABLE (XI), REX (XI).
USAGE
FUTURK
DIRECTIONS
CHANGE
HISTORY
Date
16i12188
Release
Changes
Pages
Version 2.0
initial release
ARM XI.111 24 (Release 01.00,
Internal
Functions
ANSA Reference Manual
MPSTCP(XI1
NAME
MPSTCP - a message passing service
Transmission Control Protocol.
interface
to the ARPA
PURPOSE
Implements the standard MPS interface between protocols such as
REX and GEX and the Transmission Control Protocol (TCP) which
provides a connection-oriented transport service, layered above the
Internet Protocol (IP). This manual page describes MPSTCP for the
Berkeley socket abstraction.
SYNOPSIS
#include "capsu1e.h"
#include "protoco1.h"
Status
MPS_s.tartup
(CapsuleAdr *locp,
*extra);
Cardinal
Status
MPS_send
*bufp,
(char
Cardinal
dlen,
CapsuleAdr *remp);
Cardinal
MPS_receive
(char
*bufp,
Cardinal
bmax,
CapsuleAdr *remp);
void
MPS_decay
(void);
void
MPS_cleanup
(void);
DESCRIPTION
MPS - startup initializes the TCP message passing service and tries
to acquire a non-blocking socket with a queue for incoming
connection requests. If successful, protocol_open
is called with the
pin id equivalent to this listening socket number.
If the port component of the capsule address locp is non-zero that
value is used, otherwise a port will be allocated by the system. The
remainder of locp is set to the IP host number of the machine.
On return, locp contains the complete capsule address and extra is
the size of the extra header required by this MPS for message
encapsulation.
attempts to send dlen bytes ofdata in bufp via a socket
connected to the remote capsule remp, if no connection exists and
MPS_send
ARM X1,11/ 25 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
MPSTCP(X1)
resources are available a connection will be made. Always returns
ok and relies upon protocols such as REX or GEX above to handle
failures.
MPS_receiue’s
behaviour
is determined
by value of the global
variable pin Index. If equal to the listening socket, and resources are
available, a request for connection is accepted and 0 returned.
Otherwise a connection exists and a two-part read is performed.
First the MPSTCP header is read to determine the remote capsule
address, which is placed in remp, and the length of the message. The
message is then read into bufp and the number of bytes received
returned.
If the first read gets 0, then the connection
is being
shutdown by the remote capsule and resources are released before
returning a value of 0. If the message length exceeds bmax the
message is discarded, but the actual length is still returned.
MPS_decay
is called at regular intervals by the session handler
and initiates the close down of any connections which have not been
used during the previous interval.
MPS_cleanup
is called just before the capsule expires to initiate
the close down of all connections and close the listening socket.
FILES
EKRORS
SEE ALSO
MPS TABLE
(XI), REX (XI).
USAGE
FUTUKE
CHANGE
I)IRECTiONS
The management
of resources for all connection-oriented
may be moved above the MPS interface.
HISTOKY
AR31 X1,11/26
(Release 01.00)
protocols
Internal
Functions
I
MPSTCP(X1)
ANSA Reference Manual
Date
Release
I
II
16/12/88 1 Version 2.0 1
Pages
Changes
II
initial release
ARM X1,11/ 27 (Release 01.00)
I
Internal
Functions
ANSA Reference
MPSUDP
Datagram
- a message
Protocol.
MPSUDP(X1)
Manual
passing service
interface
to the ARPA
User
PURPOSE
Implements the standard MPS interface between protocols such as
REX and GEX and the User Datagram Protocol layered above the
Internet Protocol (IP). This manual page describes MPSUDP for the
Berkeley socket abstraction.
SYNOPSIS
#include "capsu1e.h"
#include "protoco1.h"
Status
MPS_startup
(CapsuleAdr *self,
*extra.I;
Cardinal
Status
MPS_sendMsg
(char
*pkt,
Cardinal
psize,
CapsuleAdr *remcap);
Cardinal
MPS_receiveMsg (char
*pkt,
Cardinal
psize,
CapsuleAdr *remcap);
void
MPS- tick
(void);
void
MPS_cleanup
(void);
DESCRCPTION
MPS_startup
tries to acquire a nonblocking datagram socket, if the
user specifies a non-zero port in se 1f that value is used; otherwise a
system provided port will be used. The port number is cached for
use with the other interface routines. The remainder of self is set to
the If’ host number of this machine; Extra is returned as zero, as
hlf?5Lf)P needs no additional
encapsulation
header space in the
buffers.
MPS_sendMsg
attempts to send psize bytes of KEX header and
data to the nominated capsule and host. Returns transmitFai lure or
ok.
MPS
receweMsg
accepts any data waiting for this capsule, it
returns the number of bytes received and the capsule address of the
source.
ARM X1,11/ 28 (Release 01.00)
Internai
Functions
ANSA
MPSUDP(X1)
Reference Manual
and MPS
cleanup are null operations as MPSUDP has
no relevant housekeeping requirements.
MPS_tick
FILES
ERRORS
SEE ALSO
MPS (X0.
USAGE
FUTURE DIRECTIONS
Error signalling and the MaxMsg
value need to be considered.
CHANGE HISTORY
Date
1 Release
1 Pages
1
Changes
l/04/88 1 Version 1.0 1
1designed by E. Oskiewicz
16/12/88 / Version 2.0 1
I designed by E. Oskiewicz
ARM X1,11/ 29 (Release 01.00)
Internal
Functions
ANSA Reference Manual
NUCLEUS(X1)
NAME
Nucleus
- resource allocation
PURPOSE
Provides an object-like interface to the host operating system and
capsule resource allocation functions. The nucleus also contains the
capsule’s main function.
SYNOPSIS
#include
<ansa/ansa.h>
#include
"nuc1eus.h"
/* or "capsu1e.h"
ansa - Status nucleus - tasks
(Cardinal
Cardinal
ansa_Status
nucleus_socket
(Cardinal
Dispatch
ansa_ChannelId
*/
extraTasks,
stacksize);
ansa_Status
nucleus_withdraw
(ansa_ChannelId
ansa_Status
nucleusglug
(ansa ProtocolId
ansa-Endpoint
ansaICapsuleId
ansa_ChannelId
ansa_Status
nucleus_discard
(ansa_ChannelId
extern void body
(int argc,
concurrency,
*dispatcher,
*socketPtr);
socket)
;
protocol,
destination,
client,
*plugPtr);
plug)
;
char *argv[])
ansa_CapsuleId
nucleus_createCapsule
(string
string
string
void
nucleus_deleteCapsule
(ansa_CapsuleId
;
type,
arguments,
properties)
id)
;
;
[)ESCRIPTlON
The nucleus-tasks
function
enables
multi-tasking
within
the
capsule and creates extraTasks tasks with stacks of size stackSize
bytes. Tasks are anonymous and can be assigned by the interpreter
to execute any thread; but once assigned will not be re-assigned
until their thread terminates.
Stacks must therefore be large
enough to execute any thread in the capsule and (because of nested
Forks) all of its offspring.
All capsules start with one task, which
uses the main stack, nucleus - tasks can then be called to increase the
number of tasks. Because most systems only have mechanisms for
automatically
expanding or detecting overflow on the main stack,
ARM XI,11~30(Release01.01)
Internal
Functions
ANSA Reference
Manual
NUCLEUS(X1)
the sizes of any extra stacks should be generous. The nucleus
imposes a system specific minimum stack size; see “stack. h".
The nucleus_socket function allocates and initializes a socket. If
socketPtr addresses a zero index then a free socket is allocated and
its index returned, otherwise the specified socket is used. The
dispatcher argument specifies the address of the dispatch procedure
which is to service incoming invocations on the socket, and the
concurrency argument limits the number of invocations which may
be active on the socket at the same time.
The nucZeusgZug
function allocates and initializes a plug. If
plugPtr addresses a zero index then a free plug is allocated and its
The
index returned, otherwise the specified plug is used.
destination argument contains the (protocol specific) capsule
address and channel index of the socket, to which the new plug is to
be bound, and the protocol argument specifies the protocol stack to
be used for communicating with the socket. See "opt ions.h" for
those protocol stacks loaded in your capsule. The cl ient argument
must be zero or the calling capsule’s ID; it is there to allow for a
future out-of-capsule nucleus.
The nucleus_withdraw
function cancels a prior nucleus_socket
the nucleus_discard function cancels a prior nucleusqlug.
and
The nucleus also contains the function mazn for the capsule. This
performs capsule initialization and then calls the application
function body, passing on the arguments supplied to main by the
system. The capsule will not necessarily terminate when body exits,
because other threads may not have terminated and sockets may
still be active. The capsule will terminate silently with an exit
status of zero when all threads have terminated and all sockets have
been withdrawn. Premature termination with a message and
specified exit status can be forced via the Terminate instruction.
The nucleus createcapsule
fu nction creates a capsule from the
template specified by the type parameter, passing it the argument
string in the arguments parameter and initializing its environment
to the NAME=VALUE pairs specified in the properties parameter. If
successful, it returns the Capsu1e Id of the created capsule, otherwise
itreturns (ansa_CapsuleId)O.
The nucleus_deleteCapsule
of the specified capsule.
function causes the graceful termination
ARM X1,11/ 31 (Release 01.01)
Internal
Functions
ANSA
Reference
Manual
NUCLEUS(X1)
FILES
ERRORS
SEE ALSO
BINDER (XI), CHANNEL
(XI), INSTRUCT
(XI).
USAGE
All capsules must supply a body function instead of a main function.
This will normally perform the application initialization,
imports
and exports
(which will result in calls to nucleusqzug
and
nucleus_sochet)
and create any extra tasks and threads required.
Server capsules would then normally exit the body function to await
incoming invocations on their sockets, but this is only required if no
extra tasks were created to service invocations concurrently
with
body. Spawned threads will not be executed until a task becomes
free; in single-tasking
capsules this means after body has exited.
FUTURE
1)IREC’I’IONS
CHANGE
HISTORY
Date
l/04/88
16/12188
I
Release
Version
I
1.O
Version 2.0
10/4/89Version 2.5
Pages
Changes
I
initial release
function names changed according to
module naming conventions
argument types made consistent with
<ansa/ansa.h>
nucleus tasks and nucleusqlug
added
Listen removed
mam moved to nucleus and replaced by
body in application
addition of capsule creation
destruction routines
ARM X1,11/ 32 (Release 01.01)
and
Internal
Functions
ANSA Reference Manual
PIN(X1)
NAME
pin - local device control
PLJRPOSE
Provides a low level interface to the select
purpose of controlling local devices.
system
call for the
SYNOPSIS
#include <ansa/ansa.h>
#include "protoco1.h"
/* or "capsu1e.h" */
void
pin-open
pin,
void
pin-close (PinId
(PinId
void (*handler)()):
pin);
DESCRIPTION
Pins are an abstraction
of whatever
local device identifiers
are
provided by the host operating system (file descripters, sockets etc.).
They are not normally visible to applications
programs
and are
intended to increase the portability of the interpreter.
Because the
interpreter
polls or catches the interrupts
of all local devices
attached to the capsule, special arrangements
must be made for
applications
which require direct control of local devices.
Such
application
device drivers must have intimate
knowledge
of the
device control mechanisms
of the host operating system and are
therefore not portable.
The pin interface provides the minimum facilities for sharing the
device polling or interrupt mechanisms
between the interpreter
and
the application.
All the device setup and control code must be done
by the application.
The interpreter
will merely
notify
the
application when there is incoming data available, it will not read it
or execute any other function on the pin.
The pi n-open function requests the interpreter
to call the supplied
device hand 1er whenever data is available for reading.
The pi n-c 1ose function
device handler.
requests
the interpreter
FILES
ERRORS
ARM X1,11/ 33 (Release 01.01)
to stop calling
the
Internal
Functions
ANSA Reference Manual
PIN(X1)
SEE ALSO
PROTOCOL (XI), PROTOCOL TABLE (XI).
USAGE
A device handler with the following signature must be supplied by
the application:
void
handler
(PinId
pin);
This handler is run as part of the interpreter and as such has no
thread or task dedicated to it. Therefore it must not use any of the
interpreter functions that assume a thread and task. The only
function that is safe to use is spawn.
If the handler wishes to use any other interpreter functions or be
scheduled with the rest of the application threads it must perform a
spawn function to acquire its own thread. If there are not sufficient
tasks available to run the thread its execution may be delayed for
some time. It is therefore advisable for the hand 1er to close the pin
before doing a spawn in order to prevent multiple notifications of the
same event. The spawned thread must re-open the pin after it has
finished processing.
The following code fragments illustra te the use of the pin handler to
read single key presses from s tdin.
void body0
(void)system("stty raw");
/* because we spawn a thread */
nucleus_tasks(l, 0);
/* open pin for stdin */
pin_open((PinId)O, handler);
.....
pin_close((PinId)O);
(void)system("stty cooked");
void handler(pin)
PinId pin;
BufferLink buf;
/* remove handler to prevent repeat firings */
pin_close(pin);
ARM X1.11; 34 (Release 01.01)
Internal
Functions
ANSA
Reference
PIN(XI)
Manual
buf = buffer-make(O);
buf->data[O] = (char)pin;
buf->used = 1;
(void)Spawn(key, buf);
1
void key(skt, buf)
Channel Id skt;
BufferLink buf;
c
char rbuf[l28];
(void)read(O, rbuf, 1);
(void)write(l, rbuf, 1);
/* restore handler */
pin_open((PinId)buf->data[O], handler);
1
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
Release
I
20/03/89 1 Version 2.5 1
I
Pages
I
I initial release
Changes
ARM X1,11/ 35 (Release 01.01)
I
I
Internal
Functions
ANSA Reference Manual
PROTOCOL(XI1
NAME
Protocol
PURPOSE
Provides
- protocol stack handler.
housekeeping
functions
across all loaded protocol stacks.
SYNOPSIS
#include "capsu1e.h"
#include "protoco1.h"
void
protocol_init
(void)
void
protocol_open
(PinEd new)
;
void
protocol_close
(PinId old)
;
void
protocol_tick
(void)
;
void
protocol_cleanup (void)
;
DESCRIPTION
The protocoZ_mit
protocol stack.
function
;
calls the startup function
for each loaded
The protocol
open function
adds the pin (UNIX socket,
file
descriptor or similar i/o identifier) to the set on which incoming
messages can be read and processed.
The protocol_cZose function removes the pin from the set on which
incoming messages can be read and processed.
The protocol_tick
loaded MPS.
function
The protocol_cZeanup
loaded protocol stack.
calls
function
the MpsTick
function
calls the cleanup function
F[LES
ERRORS
SEE ALSO
MPS TABLE (XI), PROTOCOL TABLE (XI), REX (XI).
ARM X1,11/ 36 (Release 01.001
for each
for each
Functions
PROTOCOL(X1)
ANSA Reference Manual
USAGE
ProtocoZ_init is only called by miin in nucleus. ProtocoZ_open and
protocoZ_cZose are called by the various MPSs. ProtocoZ_tick is called
by decaysession.
Protocol_cleanup
is called by the Terminate and
Abort instructions.
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
I
Release
I
16/12/88 1 Version 2.0 1
Pws
I
Changes
1initial release
ARM X1,11/ 37 (Release 01.00)
Internal
Functions
ANSA
Reference
PROTOCOL
TABLE(X1)
Manual
NAME
Protocol
table
- a generic
interface
for protocol
handlers.
PURPOSE
The testbench
is designed
to operate
on top of a wide variety
of
protocols,
the protocols
available
may vary but all are required
to
provide the same basic service.
A map indicates
which protocols
are
loaded.
Each map entry contains
the address
of a table containing
the entry points for each of the required
protocol functions.
SYNOPSIS
#include
#include
typedef
"capsu1e.h"
"protoco1.h"
struct
Status
(*startup)
Status
(*connect)
(void);
Status
(*receive)
(void);
Status
(*send)
(void);
Status
(*reply)
(void);
Status
void
(*cast)
(void);
(*reject)
(void);
void
(*disconnect)
(void);
void
(*cleanup)
ProtocolTable;
ProtocolTable
(void);
(void):
*protocolMap[];
DESCRIPTION
All operations
are parameterless,
the session and MPS to which the
current
operation
refers
being
held in a global
data structures
indicated
by session and protocol indices.
In the case of the receive
operation
the session
is acquired
when a valid incoming
message
has arrived.
Startup
is called to initialize
the protocol and it’s protocol stack; it is
called once for each MPS in the protocol
stack,
no other protocol
operation
will be invoked
until all calls to startup have been made.
Each
time it is called
startup will notify
the interpreter
via
buffer_inzt
of the buffer
sizes required
by this protocoliMPS
combination.
An unsuccessful
return
code (= ok) indicates
that this
combination
is not available.
ARM X1.11, 38 (Release
01.00)
Internal
Functions
ANSA Reference Manual
PROTOCOL
TABLE(X1)
Connect obsolete
Recezue is called to accept the next buffer from the current MPS. In
addition to the returned status code, a global variable sessionIndex
is set to a non-zero value if the interpreter has some action to take;
otherwise it is assumed that the protocol handler has swallowed any
message which arrived.
transmits a CALL message to the remote endpoint for the
current session. It does not block, the protocol handler will cope
with retries and acknowledgements.
The interpreter will call
receive at some later time to collect the response.
Send
Reply similar to send but transmits a REPLY message to the remote
endpoint for the current session.
Cast transmits a CAST message to the remote endpoint for the
current session.
is used to make the protocol handler “forget” the last
message, it is intended to be used to erase any record of the arrival
of a CALL or CAST so that a retransmission can be processed as
though it were seen for the first time.
Reject
Disconnect
tidies up the session prior to being discarded by the
interpreter
is called once for each MPS immediately prior to the
capsule being shut down. The protocol should take the opportunity
to do any housekeeping required and to call the NPS cleanup
routine.
Cleanup
FILES
ERRORS
SEE ALSO
MPS TABLE (XI), PROTOCOL (XI), REX (XI).
USAGE
The functions for a particular protocol are called by an expression of
the form:
(*protocolMap[protocolIndexj->send)()
ARM X1,11/ 39 (Release 01.00)
Internal
Functions
ANSA Reference
PROTOCOL
TABLE(X1)
Manual
FUTUREDIRECTIONS
CHANGEHISTORY
I
I 16/12/88
Date
Release
Version
Changes
Pages
2.0
initial release designed by D. Oliver, E.
Oskiewicz.
ARM X1,11/ 40 (Release
01.00)
I
I
Internal
Functions
ANSA Reference Manual
REX(X1)
NAME
REX - an RPC interface to enable object interaction.
PURPOSE
Provides an RPC service which conforms to the standard interface
for remote interaction, regardless of the underlying message
passing service.
SYNOPSIS
Status
Status
rex_startup
rex_send
(void);
(void);
Status
rex_reply
(void);
Status
rex_cast
(void);
Status
rex_receive
(void);
(void);
Status
rex_connect
void
rex_disconnect (void);
void
rex_reject
(void);
void
rex_cleanup
(void);
void
rex_printstats (FILE *fd);
DESCRIPTION
These operations are used by the interpreter to invoke REX activity.
With the exception of rexprintstats,
they are invoked via the
protocol table and are parameterless (because all pertinent details
are recorded in global data structures).
ensures that REX and its message passing services are
initialized and available for use. Each MPS allocates a unique id for
this capsule and also indicate their maximum packet size and
header requirements.
Rex-startup
REX provides three message sending operations: ren_send,
rex_cast,
and rex_repZy.
These are all non-blocking, i.e. they
return when the message has been sent or a locally detectable error
occurs. Buffers which are too big to be sent in one packet are
transparently sent as a stream of fragments. Some hardware
architectures limit the maximum size of a standard contiguous
region of memory and this will limit the sizes of buffer which may be
sent or received.
ARMXI,ll/
41(Release01.00)
Internal
Functions
ANSA Reference Manual
Rex-send
is used to send a call
REX(X1)
message,
a reply is expected
in
return.
Rex-reply
is used to send the reply to a call.
Rex-cast
is used to send a cast message
for which
no
acknowledgement
or reply is expected. Although rex_cast returns
the same error codes as rex send this is intended as advice because
no error recovery will be attempted by REX.
There is one message
reception
operation:
Rex_receiue
is used to accept and predigest incoming messages.
It
will quietly assemble
fragmented
buffers,
discard
erroneous
messages and retransmissions
and send acknowledgements.
The outcome of rex receive depends on three reply values, a status
code, a session index and the state of the session referenced by the
If the message requires further
action by the
session index.
interpreter
then sessionIndex is non zero, otherwise
there is
nothing further for the interpreter to do.
The decision to call rex receive is made by the interpreter
uses the select system caTto poll the capsule’s socket.
There are four housekeeping
Rex-connect
which
operations:
is a null operation,
it always returns
ok.
Rex-disconnect
is called to to do housekeeping
before a session is
discarded,
it’s main actions
are acknowledging
unanswered
messages and disarming unfired alarms.
Rex_reJect
is used by the interpreter
to cause REX to forget casts or
unacknowledged
calls which have been received.
This involves
discarding buffers and resetting sequence numbers.
Rex-cleanup
is called prior to capsule termination,
this releases
any resources acquired and calls the current MPS cleanup routine.
It also calls rexdrmtstats.
There is an additional
operation,
intended
for developers:
rexJrmtstats,
if statistics gathering
is enabled, causes REX ta
dump statistics
about messages
sent and received
and errors
detected; otherwise it has no effect.
The following
timer fires:
timer
operations
are called when
ARM XI,1 l! 42 (Release 01.00)
a REX initiatec
Internal
Functions
ANSA Reference Manual
lWX(XI)
is used to control the rate of transmission of fragments,
this timer is armed when the first fragment is sent. Each time
rexfzow is called it sends the next fragment of the current buffer.
When the last fragment has been sent it arms a flow probe timer,
otherwise it re-arms the flow timer.
Rexdow
is used to solicit a fragnack by retransmitting the
first fragment (up to some threshold).
RexflowProbe
Rex_checkFragmentProgress
is called when progress is not being
made in a fragmented transfer. It constructs and sends a fragnack,
if a threshold of unanswered fragnacks is exceeded, the incoming
message is abandoned.
is called when a timeout occurs. This timer is armed
whenever a reply is expected in response to a message sent. Each
time rex -retry is called it resends the message and rearms the retry
timer (subject to limits determined at compilation time).
Rex-retry
The REX procedures make use of an interface to an idealized
message passing service (see MPS TABLE (XI)) to insulate themselves from the protocols, topology and hardware used by lower
layers.
FILES
ERRORS
SEE ALSO
INTERPRET (XI), MPS TABLES(XI), MPSUDP(XI), MPSTCP(X1).
USAGE
FUTURE DIRECTIONS
CHANGE HISTORY
ARM X1,11/ 43 (Release 01.00)
Internal
Functions
Date
l/04/88
ANSA
Release
I
I
1Version 1.0 1
1
16/12/88
1 Version 2.0 1
Reference
REX(X1)
Manual
Changes
Pages
1written by E. Oskiewicz
I
written by E. Oskiewicz
ARM X1,11/ 44 (Release 01.00)
Internal
Functions
ANSA
Reference
Manual
SCHEDULE(XI)
NAME
Schedule - controls task, thread, message and alarm scheduling
PURPOSE
Provides a comprehensive scheduling service for a capsule. Waiting
messages are read and processed, alarms processed, threads woken
or dispatched, threads assigned to tasks and tasks executed or
resumed.
SYNOPSIS
#include "capsu1e.h"
#include "schedu1e.h"
void schedule
(void)
void schedulego
(void)
;
;
DESCRIPTION
The schedule
function assigns free tasks to execute queued threads,
resumes unblocked tasks, receives incoming messages and processes
alarms. If the calling thread/task is ever resumed, schedule will
return. If the tailing thread has finished its execution, both the
thread and task should be freed before calling schedule.
The schedule_poll function reads any queued messages and queues
(wakes or dispatches) a thread to process each one, before returning.
FILES
ERRORS
SEE ALSO
INSTRUCT (XI), NUCLEUS (XI), REX (XI).
USAGE
The schedule function is called by those instructions that block the
calling thread, or by the nucleus when the execution of the calling
thread is complete. The scheduleqoll
function is only used by the
Pause instruction before waking its calling task and calling
schedule.
ARM XI,1 1/ 45 (Release 01.00)
Internal
Functions
ANSA Reference
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
l/04/88
Release
Pages
Version 1.0
( 16?12/88~ Version2.0 /
SCHEDULE(XI)
Manual
Changes
initially released as part of INTERPRET
1schedule split off into its own module
scheduleqoll
function added to
support the Pause instruction
ARM X1,11/ 46 (Release 01.00)
In ternal
Functions
ANSA Reference
SESSION(X1)
Manual
NAME
Session - manages the capsule’s session table.
PURPOSE
Provides the storage and management of communications session
A session is a temporary association between two
data.
communications endpoints whose lifetime is suficiently long that
all the required guarantees and constraints can be maintained.
Session table entries are purged after they have been dormant long
enough to guarantee that there are no messages still in transit.
(Strictly speaking each capsule only manages its own half-session.)
SYNOPSIS
#include "capsu1e.h"
#include "sessi0n.h"
(void)
void
session_init
Status
session_invalid
(SessionId
index)
void
session- select
(SessionId
index)
Status
session_selectOutgoing (ChannelId
Cardinal
Status
session_selectIncoming (ChannelId
destchannel,
SessionId
destsession,
Endpoint
*sourceEndPtr,
SessionId
sourceSession
InterfaceId ifID) ;
void
session- setState
;
;
;
sourcechannel,
sequencing) ;
(SessionSt
new)
Boolean session_testFlag
(Cardinal
flag)
void
session_setFlag
(Cardinal
flag)
void
session_clearFlag
(Cardinal
void
session- decrement
(void)
void
session- attachBuffer
(BufferCink buffer)
void
session detachsuffer
(void)
void
session setAlarm
(MilliSecs
Action
void
session- clearAlarm
(void)
Time
session- readAlarm
Action
session_triggerAlarm
;
;
;
flag) ;
;
;
;
;
(void) ;
(void) ;
ARM X1,11/ 47 (Release 01 .Ol)
delay,
action)
;
Internal
Functions
ANSA
void
Reference
session_disconnect
SESSION(X1)
Manual
(void)
;
DESCRIPTION
The session_init function creates and initializes the session
This
is later
expanded
by session_seZectOutgoing
session_seEectIncomtng
as required.
The session_inuaZzd
range.
function
checks
if the session
index
table.
and
is out of
index is in range
The session_seZect function checks if the
and then selects the indexed entry as the current one by setting the
global variables sessionIndex to its index and sessionptr to its
address.
The session seZectOutgotng function selects the session table entry
for the specified channel and current thread; either by locating an
existing one or by creating a new one. If the sequencing argument is
SEQUENCED then invocations of the same channel by the same thread
are sequence preserving; otherwise if it is UNSEQUENCED then there
are no sequencing guarantees which need to be preserved.
The session_selectIncoming
function selects the session table entry
for the message just received; either by locating the specified session
or, if it has been re-used, by creating a new one.
The sesston_setState
function changes the current
and if the new state is IDLE sets the decay alarm.
session’s
state
The session_testFlag,
session_setFlag
and session_clearFlag
functions perform the obvious operations
on one of the current
session’s flags without disturbing the others.
The sesston_decrement
function decrements the current session’s
sequence number after a message has been rejected so as to avoid
rejection of a re-transmission
as a duplicate.
The session_attachBuffer
and session_detachBuffer
functions attach
and detach a buffer to the current session, freeing or swapping any
existing buffers according to the session state.
The session_setAlarm,
session_clearAlarm,
sesston_readAlarm
and
session - triggerAlarm
functions control the alarm for the current
Session_setAZarm
aborts if an alarm is already set, but
session.
will
re-clear
a cleared
alarm.
session
clearAlarm
Session_readAZarm
non-destructively
reads thew first alarm set.
Session_triggerAZarm
clears the first alarm that has fired and
ARM X1,11/48 (Release 01.01)
Internal
Functions
ANSA Reference Manual
returns
a pointer
to the
action
SESSION(X1)
function
specified
to
session - setAlarm.
The session_disconnect
function arranges for the disconnect
function of the current session’s protocol to be called when the
session state becomes IDLE and to free the session.
FILES
ERRORS
SEE ALSO
INSTRUCT (XI), NUCLEUS (XI), REX (XI).
USAGE
Sesszon_init is only called by the main function in the nucleus.
Sesslon_selectOutgoing
is called by those instructions
that
implement inter-capsule communications. Session_~eZectIncoming
is called by the protocol handlers as soon as they receive a message.
is only called by channel_cEeanup.
Session_disconnect
FUTURE DIRECTIONS
Currently sessions are only robust in the face of passive
To survive malicious
attacks,
communication
failures.
challenge/response functions within a secure protocol are required
for the re-establishment of dormant sessions.
CHANGE HISTORY
I
Date
Pages
Release
I
I
l/04/88 1Version 1.0 1
16112188
Version 2.0
lo/O4189 Version 2.5
I
initially released as part of INTERPRET
completely redesigned as a separate
module
addition of ifID to selectIncoming
ARM X1,11/ 49 (Release 01.01)
Internal
Functions
ANSA Reference Manual
STACK(XD
NAME
stack - stack handler.
PURPOSE
Provides register dumping and stack switching functions to support
multi-tasking.
The implementation
of multi-tasking
is designed to
use the standard C library functions setjmp and longimp whenever
possible so as to increase portability by avoiding assembler code for
register manipulation.
The actual switching of stacks is done by
altering
the saved values of the stack front and stack frame
registers in the RegDump before calling stack-switch.
Unfortunately,
some implementations
of longlmp check that Zongjmp is being called
by a more deeply nested function than setjmp. For these systems,
equivalent assembler routines must be written; otherwise the stack
functions are just macro definitions of setjmp and Zongjmp.
SYNOPSIS
#include "stack.h"
int
stack-dump
(Regllumpenv)
void
stack-switch
(RegDump env, int val)
;
;
DESCRIPTION
See setjmp and Zonglmp in the UNIX manual.
FILES
ERRORS
SEE ALSO
SCHEDULE
(XI), TASK (XI), THREAD (XI).
USAGE
Stack-dump
Stack-switch
is only used to define
the task-dump
is only used by task_swltch and task_dzspatch.
FUTURE
DIRECTIONS
CHANGE
HISTOKY
ARM X1,11/ 50 (Release 01.00)
macro.
Internal
Functions
Date
16112188
ANSA Reference
Release
Version
Pages
2.0
STACK(X1)
Manual
Changes
initial release
ARM X1,11/ 51 (Release
01.00)
Internal
Functions
ANSA
Reference
SYSTEM(X1)
Manual
NAME
System - interfaces to the host operating system.
PURPOSE
Provides indirect access to the necessary functionality of the host
operating system. The only other modules which call the host
operating system directly are the various MPS modules.
SYNOPSIS
#include
"capsu1e.h"
#include
"system.h"
void
system_init
(void)
;
Cardinal *system-allocate
(Cardinal
Cardinal *system-extend
(Cardinal
Cardinal
*pointer,
bytes) ;
bytes)
void
system-free
(Cardinal
*pointer)
Set
system-wait
(Time
alarm)
void
system_HtoN
(Cardinal
CapsuleAdr
type,
void
system_NtoH
(Cardinal
CapsuleAdr
*ca)
;
*al,
11,
*a2,
12)
;
*ca)
;
;
;
type
9
int
system_ipc - heq
(u char
Cardinal
u char
Cardinal
void
system_genIfID
(InterfaceId
ifID)
int
system_cmpIfID
(InterfaceId
InterfaceId
ifl,
if2)
void
system_copyIfID
(Interfaceid
InterfaceId
to,
from)
;
void
system_putIfID
(char
InterfaceId
*bf,
ifID)
;
(char
InterfaceId
*bf,
ifID)
;
void
system_getIfID
int
system_allocateRef
void
system_freeRef
(InterfaceId
AddressHint
InterfaceRef
(InterfaceRef
ARM XI,1 li 52 (Release
;
;
id,
ah,
*ref)
*ref)
01.01)
;
;
;
Internal
Functions
ANSA Reference
Cardinal
system-time
DESCRIPTION
The system-i&
SYSTEM(X1)
Manual
(void)
;
function performs system specific initialization.
The system_aZZocate function allocates an area of memory which is
at least the requested number of bytes long. The system-extend
function extends a previously allocated area to the requested size; if
extension in-situ is not possible, a new allocation will be made, the
contents of the old area will be copied to the start of the new one and
the old area freed. If successful both functions return a (wordaligned) pointer to the area; otherwise they return NULL. Neither
function initializes the newly allocated or extended memory.
The systemfree
function
extended area of memory.
de-allocates
a previously
allocated
or
The system-wait function performs a timed-out read of the capsule’s
i/o pins (UNIX sockets, file descriptors, TSAPs
etc.). The exact
nature of a specific pin is known only by the system and MPS
modules. The protocol module keeps track of which pins are in use
and which protocol stack is servicing each pin. System_wait returns
the set of pins for which there are messages waiting to be accepted;
if the alarm triggered, this set will be empty.
The system HtoN function and the system_NtoH function cause any
structureditems
in a capsule address to be converted from host to
network format and network to host format, respectively.
The
system_qc_heq
function compares two IPC addresses, returning 0 if
they are the same, non-zero if they are different.
The system_genlflD
function generates
a new InterfaceId.
The
system_cmpIflD
function compares two InterfaceId’s, returning 0 if
they are the same. The system_copylflD
function copies the value of
from to to. The system_putlfID
function
creates
a string
representation
for the InterfaceId in the buffer provided, while the
systemxetlflD
function creates an InterfaceId
from the string
representation in bf.
The system_alZocateRef function generates an InterfaceRef from the
InterfaceId and AddressHint
provided, returning a pointer to the
allocated InterfaceRef.
The return value of the function
is 1 if
successful, 0 if not. The systemfreeRef
function returns storage
allocated in a previous call to system_ulZocateRef.
ARM X1,11/ 53 (Release 01.01)
Internal
Functions
ANSA Reference
SYSTEM(X1)
Manual
The system-time
function returns a representation
of the current
time as a Cardinal. The units of this value is deemed to be seconds.
FILES
MASTER-FILE
(definedin options.h,
but normally /usr/local/etc/ansa/masteraddress)
TRADER-FILE
(definedin options.h,
butnormally
/usr/local/etc/ansa/traderaddress)
If MASTER-FILE exists, it is assumed to contain the address of the
master trader to be used by capsules on this host, overriding the one
in 0ptions.h. If TRADER-FILE exits, it is assumed to contain the
address of the default trader to be used by capsules on this host,
overriding the one in opt ions.h. A trader address is an ASCII string
in the same (protocol
specific)
format
as the definition
of
TRADER-ADDRESS in options. h, but without the enclosing
double
quotes.
ERRORS
SEE ALSO
MPS (XI), PROTOCOL
(XI).
USAGE
System_init is only called by the main function in the nucleus and
must be the first initialization
function called. System-wait is only
called by schedule. System allocate, system-extend
and systemfree
are a repackaging
of the Clibrary
routines malloc, rea2Zoc and free
to use word aligned pointers and provide a single monitor point for
memory usage.
FUTURE
DIRECTIONS
CHANGE
HISTORY
Date
Release
I
Changes
Pages
16/12/88
Version
2.0
initial release
10/4/89
Version
2.5
addition of InterfaceId,
and time routines
ARMXI,ll/
54(Release01.01)
InterfaceRef
Internal
Functions
ANSA Reference Manual
TASKGSI)
NAME
Task - multi-tasking support.
PURPOSE
Provides the task management functions required to execute more
than one thread at a time. A thread is an independent execution
path which can be executed concurrently with other threads. While
a thread is being executed, it requires a stack to store local variables
and function return links; when a thread is blocked, it requires a
register dump area to save the processor state so that the processor
can execute another thread.
A thread only needs a register dump and stack while executing;
these are provided by a task so that an executing thread may be
blocked to allow other tasks to execute their threads. Tasks are
significant resources and their unrestricted creation can easily
exhaust the available memory. Therefore the number of tasks in a
capsule is controlled by the application via the nucleus-tasks
function.
This restriction on the number of tasks is dealt with by serializing
the execution of any excess threads. A deadlock may occur if an
executing thread blocks waiting for a thread which has not started
executing due to resource limitations. This is avoided by nesting
the execution of the thread being waited for, on the task of the
waiting thread. In the current implementation, this can only occur
if a parent thread tries to join with a child thread which has not
started executing. Because of this thread nesting, the stack sizes
should be calculated on the basis of executing all potential offspring
on the same task.
SYNOPSES
#include "capsu1e.h"
#include "task.h"
void
task_init
(void)
void
task-setup
(void)
Status
task-make
(Cardinal
Cardinal
;
;
extraTasks,
stackSite) ;
void
task-select
(TaskId
index)
void
task-wake
(TaskId
index)
void
task_setThread
(void)
;
ARM X1,11/ 55 (Release 01.00)
;
;
Internal
Functions
ANSA Reference Manual
int
task-dump
void
task-switch
void
task-dispatch
void
task-free
TASK(X1)
(void)
;
(void) ;
(void) ;
(void) ;
DESCRIPTION
The tush init function creates and initializes
the task table to
contain the dummy (zero) entry and an entry for the capsule’s initial
task which uses the main stack. The taslz,setup function sets up the
initial stack dump for task 1 by copying the dump for the dummy
entry and saving the stack front and stack frame pointers.
The tush-m&e
function
creates and initializes
extra tasks.
The task-select function makes the specified task table entry the
current one by setting the global variables taskIndex to its index
and taskPtr to its address.
_
The task_wake function puts the specified task onto the end of the
queue of tasks that are eligible for execution.
The ta.sk_setThread
current task.
function
assigns
the current
thread
to the
The tusk-dump function dumps the registers in the current task’s
dump area. The exit from the initial call of tusk-dump will return a
zero result; subsequent exits from task - dump caused by task-switch
will return a non-zero result.
The task_switch function dequeues the first task that is eligible for
execution, selects it and switches to its stack, resuming execution by
restoring the registers and simulating another exit with a non-zero
result from the last task-dump executed on that stack.
The task_dispatch function
free tasks and starts the
selecting it and its thread,
copying the dump from the
and stack frame registers
task_switch
to the original
thread-execute
call following
dequeues the first task from the pool of
execution
of its assigned
thread by
re-initializing
its register dump by
dummy task, resetting the stack front
in the dump and then simulating
a
task-dump
in main, which has a
its non-zero return branch.
The taskfree
function puts the current task into the pool of free
tasks and then checks if there is any more work for the capsule to do.
ARM X1,11/ 56 (Release 01.00)
Internal
Functions
ANSA Reference
TASK(X1)
Manual
If there are no active tasks, threads queued for execution or open
sockets, then the capsule is terminated.
FILES
ERRORS
SEE ALSO
NUCLEUS (XI), SCHEDULE (XI), STACK (XI), THREAD (XI).
USAGE
Tash_init and tash_.setupare only called by the main function in the
nucleus. They must be separated only by a call of task-dump. This
is done so that the register dump can be taken at the top level.
Task-make is only used to implement nucleus-tasks.
Task-dump is
only used in mavt and schedule. Task-dispatch and task-switch are
only used in schedule.
FUTURE DIRECTIONS
CHANGE HISTORY
IDate/
p-I Pages
1 16/12/88 1 Version 2.0 1
/
Changes
I initial release
ARM X1,11/ 57 (Release 01.00)
I
Internal
Functions
ANSA Reference Manual
THREAD(XD
NAME
Thread
- multi-threading
support.
PI RPOSE
Provides the thread management
functions required to support the
execution of more than one thread at a time. A thread identifies an
independent
execution path which can be executed concurrently
with other threads.
Threads are created as a result of Fork and
Spawn instructions
or incoming invocations (Dispatch). There is no
limit imposed on the number of threads that can be created in a
capsule, but the number of active threads allowed on each socket is
specified by the application when the socket is created.
SYNOPSIS
#include
"capsu1e.h"
#include
"thread.h"
void
thread_init
(void)
void
thread-select
(ThreadId
;
index)
;
Status
thread-invalid
(ThreadId
thread)
ThreadId
thread-parent
(ThreadId
thread)
ThreadSt
thread-state
(ThreadId
thread)
void
thread_setState
(ThreadSt
new)
void
thread_setSession
(void)
void
thread-queue
(ThreadId
ThreadId
*head,
thread)
*head)
;
;
;
;
;
ThreadId
thread_dequeue
(ThreadId
void
thread - wake
(ThreadId
ThreadId
thread-dispatch
(ThreadId
Dispatch
ChannelId
BufferLink
void
void
thread-execute
(void)
void
thread-nest
(ThreadId
void
thread-free
(void)
;
;
thread)
;
parent,
*dispatcher,
socket,
buffer,
(*epilogue)())
;
;
ARM X1,11/ 58 (Release 01.00)
child)
;
;
Internal
Functions
ANSA
Reference
Manual
THREAD(X1)
DESCRIPTION
The thread-i& function creates and initializes the thread table to
contain the dummy (zero) entry and an entry for the capsule’s initial
thread.
The thread-select function makes the specified thread table entry
the current one by setting the global variables threadIndex to its
index and threadPtr to its address.
The th read-invalid
range.
function checks if the
The threadgarent
thread.
function returns the parent of the specified
The thread-state
index is out of
function returns the state of the specified thread.
The thread_setState
The thread_setSession
current thread.
function changes the current thread’s state.
function assigns the current session to the
The thread-queue function puts the specified thread onto the end of
the specified queue.
The thread_dequeue function dequeues and returns the first thread
from the front of the specified queue. If the queue was empty then a
zero index is returned.
The thread wake function wakes up the task that the specified
thread is assigned to.
The thread-dispatch function creates a new thread, initializes it and
queues it waiting for a free task to execute it. The socket and buffer
arguments are passed to the dispatcher function and the epilogue
function is called after the dispatcher has returned in order to
perform any required termination operations, such as waiting for its
parent to join it or sending a reply.
The thread-execute
function executes the current thread on the
current task by calling its dispatcher and epilogue functions.
The thread-nest function takes the child thread off the thread
queue, executes it on the current task and then returns to the parent
thread.
The threadfree
free threads,
function puts the specified thread into the pool of
ARM X1,11/ 59 (Release 01.00)
In ternal
Functions
THREAD(X1)
ANSA Reference Manual
FILES
ERRORS
SEE ALSO
INSTRUCT
(XI), SCHEDULE
(XI), TASK (XI).
USAGE
FUTURE
DIRECTIONS
CHANGE HISTORY
b
Date
1 16/12/88
Release
Changes
Pages
1Version 2.0 1
I initial release
ARM X1,11/ 60 (Release 01.00)
I
I
Part XI
Chapter 12
Installation
This chapter describes the installation
ANSA Testbench has been ported.
12.1
UNIX
12.1.1
The testbench
procedures
for systems
to which the
distribution tape
The testbench software is delivered on a tar format cartridge tape and has
been checked on a SUN 3~10 running SUI-IOS~
and a Hewlett Packard 9000
model 350 running HP-LX'.
The tape contains C language sources for the interpreter, the nucleus, REX,
the trader, the stub compiler, and the distributed processing language preprocessor.
An installation
script is provided to enable these files to be
unpacked and compiled. Some test programs are also provided to ensure that
the installation was successful.
To run the script and do a successful
following programs need to be available:
installation
of the testbench,
the
/bin/sh, /bin/csh (Bourne and C shells), ar, as, awk, cat, cc,
cp, date, echo, In, make, mkdir, mv, pwd, ranlib, rm, tee, yacc
The testbench also requires the UDP protocol,
named pipes in order for REX to work.
12.1.2
Preparing
In order to successfully
1)
2)
3)
4)
and/or
to read the tape
complete the installation
process you must:
decide where to place the testbench source, include and library files
determine which host on your network will be running the trader
determine your system type (currently one of sun, hpux, or m6000)
determine which MPS modules you wish supported
‘SunOS is a trademark
P-LX is a trademark
‘If
and/or the TCP protocol,
of Sun Microsystems
of Hewlett-Packard
Company
ARM XI, 12 / 1 (Release 01.01)
ANSA
5)
determine
Reference
the device which contains
Manual
the installation
tape.
These options are discussed below.’
12.1.2.1
The testbench logical root directory
This directory will be used to contain all the testbench sub-directories
used as a source of libraries and header files by application programmers
developers. We recommend that you use:
and
and
/usr/local
Your chosen directory must be your current working directory when you
read the distribution tape. Whichever directory you choose must be readable
by all users who need to access the testbench files and will have the following
sub-directories
created if they do not already exist:
src, lib, include, etc, bin
12.1.2.2
The trader host
The host machine chosen to support the trading service must be decided
before the installation
process begins. The host chosen must be accessible by
all machines running the testbench and must be suitable for supporting
a
pivotal network service, i.e. it should be a reasonably stable machine which
is not unduly subject to crashes or reboots. You must provide the host’s name
during the installation
process and it must be the same for all machines on a
given network.
N.B. the installation
script is unable to detect if you provide
a bogus host name.
The name given must be a legitimate
host name which matches
the entry in
If you provide an unsuitable
name the
letclhosts
exactly, case is significant.
installation
process will complete but the resulting
library will be useless.
12.1.2.3
The host system
The testbench must be built afresh for each system type. Currently
the
installation
should work without modification
for SUN and HP-CX systems.
The system type chosen is used to generate appropriate
Makef i1e ’ s for the
build process (the difference
is in the libraries
needed to compile the
testbench source files).
12.1.2.4
The MPS modules
This release of the testbench supports REX’s use of multiple MPS modules for
remote interactions.
Optimized calls between capsules on the same host can
be achieved if the IPC MPS is included.
SIPS’s based upon CDP and TCP are
also provided for conveying messages between capsules on different hosts.
While both UDP and TCP can be included in the capsules, the current system
ARM XI, 12 / 2 (Release 01.01)
Installation
will always choose UDP preferentially. As a result, the default set of MPS'sis
"IPCUDP".
Note that if one system is built with UDP as the sole remote MPS and another
is built with TCP as the sole remote _hlPS
then capsules on these systems will
not be able to interact.
12.1.3
Installing the testbench
N.B. all example commands shown in this appendix assume that the user is
running in the C shell. Set your current working directory to your chosen
testbench logical root directory, load the tape in a cartridge drive and type
the following:
tar xvbf
1
/dev/yourTapeDevice
Assuming that you have write access to this directory and its sub-directories,
tar will now unpack all the installation files. At the end of the process (a
couple of minutes at most) you will find the installation
script ( InstallANSA)
in the directory. You run this script (and capture the output in a logfile) by
typing:
InstallANSA
I& tee Install.log
The script begins by asking five questions. You may abort the installation
by typing the seven characters *ABORT* in response to any of the first four
questions. The script provides a lot of detail about the actions you are being
asked to undertake.
First you are asked to provide the testbench logical root directory (you must
type an absolute pathname,
e.g. /foe/bar), the default is your current
working directory.
Second you are asked to enter the trader host name. This name must exist in
/etc/hosts
and case is significant.
The default is the current hostname.
Third, you are asked to provide the list of MPS modules desired for this
system - the list is simply a blank-separated
sequence of the words IPC,C'DP,
and TCP. The default list is: IPC CDP.
Fourth you are asked to enter the system type (one of sun, hpux, or m6000).
Finally, you are asked if you wish to delete object and other intermediate
files generated during the installation.
The default action is not to delete
the intermediate
files.
The script takes 10 to 15 minutes to run, much of which is spent compiling.
In the event of errors, use the log file to determine what the problem is.
ARM XI, 12 / 3 (Release 01.01)
12.1.3.1
Non-standard
port numbers
The testbench installation assumes two UDPITCPport numbers that are fixed.
One of these (port number 1100) is for the trader and should not be changed
without good reason, the other (port number 1060) is for a test program
used for pre-trader checkout and may be changed if necessary. To change
either of these values after the installation, proceed as follows - it is assumed
that the starting directory is the testbench logical root denoted as SR:
To change the port number for the test program:
cd $R/src/ansa/test
edit both cal1Server.c and cal1Stub.h to change
#
"#define callcapsule 1060" to your chosen value
#
make
cd $R
Changing the port number for the trader should not be undertaken lightly
and involves a rebuild of the trader AND modifications to a file on each of the
other hosts in the system. If it must be done, proceed as follows:
cd $R/include/ansa/capsule
edit 0ptions.h to change
#
"#define TRADER_UDP_PORT 1100"
#
"#define TRADER_TCP_PORT 1100"
#
to your chosen value
#
cd $R/src/ansa/trader
make trader; make tinstall
Now you must create the file $R/etc/ansa/traderaddress on each non-trader
host. This file contains a single line; this line has the same format as the
TRADER ADDRESS symbol in $R/include/ansa/capsule/options.h, minus the
quotation marks. For example, if the opt ions. h file on a particular host had
the following definition:
#define TRADER-ADDRESS "1:1.2.3.4:1100:2"
to
and you have just changed
TRAD ER_UDP_PORT
$R/etc/ansa/traderaddress shouldcontain the following line:
4321,
then
1:1.2.3.4:4321:2
12.1.4
Installation tests
The installation script builds a number of test programs: the most basic one
tests out the interpreter and KEXin isolation. To run this do the following
(from the test bench logical root directory)
ARM XI, 12 / 4 (Release 01.01)
Installation
src/ansa/test/cal server &
src/ansa/test/cal client -ilOO
This will repeatedly issue REX calls and collect the replies reporting the
elapsed time and buffer sizes every 100 calls (about twice a second on a SUN).
You can change the number of iterations by altering the number in the
callclient line and can even nominate a different host, e.g.
src/ansa/test/callclient -ilOOO SomeOtherHost
By default, the callclient test runs endlessly. Use the
-p<# of passes
option to cause it to terminate after < # of passes >
By default, callclient uses UDP for its interactions. Use the -mipc flag to
cause it to use the IPCMPS (the server had better be on the same host) or
-mtcp to cause it to use TCP. Obviously, if you specify an MPS for which
support was not included during the build, you will get a bind failure.
The callserver must be terminated by using the ki11 command.
12.1.4.1
Startmg the trader and exercising
it
Before any of the other test programs can be started, it is necessary that the
trader be started on the host which was nominated during the build
procedure. Assuming that the current working directory is the testbench
logical root, the following command starts the trader:
etc/ansa/trader >&etc/ansa/trader.log &
Depending upon the MPS support selected, you should see one (or more) of the
following (after invoking netstat -a and 1s /usr/tmp):
b
UDP port 1100 exists
)
TCP port 1100 has a LISTENoutstanding
)
the fifo /usr/tmp/ansa. 1 exists
Three tests which use the trader can now be performed.
1.
When the trader starts up, it registers itself as the exporter of two
additional services: TrCtxt and TrType.
The following commands
should yield information on these two service offers:
src/ansa/trader/trlook TrCtxt /
src/ansa/trader/trlook TrType /
2.
The trsearch command causes information on all offers matching the
type specified in the nominated trading scope to be returned.
ARM XI, 12 / 5 (Release 01.01)
ANSA Reference Manual
src/ansa/trader/trsearch ansa /
causes information about all known offers to be displayed (since all
types are sub-types of type ansa).
3.
Next launch a number of Lookup requests at the trader, keeping track
of the elapsed time. This is done as follows:
src/ansa/trader/trtest
This program will request the offer information on the TrCtxt offer
1000 times, and prints summary statistics of the performance upon
completion. For those who truly want to exercise the trader, trtest
takes an optional argument which is the number of times the 1000
requests should be attempted.
When you are satisfied that the trader works correctly, the startup command
line should be added to /etc/rc; this guarantees that the trader is started
everytime the system boots up. Obviously this should follow any commands
which are necessary to enable the network!
12.1.4.2
The Echo service
Now that the trader is working, all other services are provided by normal
capsules.
The simplest of the example services provided with the
distribution tape is an Echo service. To start the Echo server, issue the
following command line:
src/ansa/Echo/server %.rc/ansa/Echo/server.log
&
The followi ng command line shows that the server actually posted its offer to
the trader:
src/ansa/trader/trlook Echo /
Three client programs are provided which use the Echo service:
1.
cl i ent simply reads each line from its standard input, invokes the Echo
function of the Echo server, and prints the echoed line on the standard
output.
2.
techo invokes the Echo function of the Echo server with a fixed size
buffer of characters a given number of times. Upon completion,
summary statistics about the transfer rate are displayed.
3.
tsink invokes the Sink function of the Echo server with a fixed size
buffer of characters a given number of times. Upon completion,
summary statistics about the transfer rate are displayed.
The following
previously:
command lines will exercise
the Echo
ARM XI, 12 / 6 (Release 01.01)
server started
Installation
src/ansa/Echo/client <InstallANSA
src/ansa/Echo/techo -bl -nlOOO
src/ansa/Echo/techo
src/ansa/Echo/techo
I diff - InstallANSA
-blO -nlOOO
src/ansa/Echo/techo
src/ansa/Echo/tsink
src/ansa/Echo/tsink
src/ansa/Echo/tsink
src/ansa/Echo/tsink
-blOO -nlOOO
-blOOO -nlOOO
-bl -nlOOO
-blO -nlOOO
-blOO -nlOOO
-blOOO -nlOOO
For both techo and tsink, you may optionally specify the name of another
host upon which the service is active with a command of the form:
src/ansa/Echo/techo -bl -nlOOO OtherHostName
12.1.4.3
The Sample service
The Sample service is provided to illustrate an interface specification
with
multiple operations. One of the operations returns multiple results, another
takes no arguments, while the third returns no results. Starting the server
requires the command:
src/ansa/Sample/server >&src/ansa/Sample/server.log &
The client simply invokes each operation 1000 times, printing the results
from the two operations which return results on the standard output. After
checking that the service offer was registered with the following command:
src/ansa/trader/trlook Sample /
the following command is suggested
for exercising
the client:
src/ansa/Sample/client I wc
12.1.4.4
The Netinfo service
The Netinfo service is provided as an example of a non-trivial application of
the ANSA testbench.
Each UNIX system which supports
the socket
abstraction for interfacing to the TCP/L!DP/IP
family of protocols provides a set
of library routines which permit the programmer
to determine information
about hosts, networks, protocols, and services. The usual implementation
of
these library routines is to read the appropriate information
from a set of
distinguished
files which are stored in /etc, returning to the caller a pointer
to some statically stored data structures which have been loaded with the
appropriate
information.
One complication
of this
particular
implementation
style is the necessity
to keep multiple
copies of the
distinguished
files consistent.
The Netinfo
service
is a simple
implementation
of a name service which eliminates
this consistency
requirement.
ARM XI, 12 / 7 (Release 01.01)
ANSA Reference Manual
provides an RPC interface
to the routines
gethostbyname(),
getnetbynameo,
getprotobyname(),
and getservbynameo.
The return results
from the remote procedure
calls are discriminated
unions (specified as
CHOICE’s)in which the full data structure is returned only if the lookup on the
server host was successful.
The specification
and the client and server
programs can be consulted for more information.
To start up the server, use
the following command:
Netinfo
src/ansa/Netinfo/server
S&src/ansa/Netinfo/server.log &
Four client programs are provided, each one exercising a different operation
in the interface. The following command lines should result in useful output
from the client. programs (note the backquotes in the second line):
src/ansa/trader/trlook Netinfo /
src/ansa/Netinfo/hclient 'hostname'
src/ansa/Netinfo/nclient arpa
src/ansa/Netinfo/pclient udp
src/ansa/Netinfo/sclient tcp ftp
12.1.4.5
The test1 service
This service is exactly the one described in section 3.4 of this manual.
start up the server, use the following command:
To
src/ansa/testl/server >&src/ansa/testl/server.log &
The client program can be invoked as:
src/ansa/testl/client 1 2 3 4 5
12.1.5
Support and further developments
The ANSA testbench software is being made available
in source form to
enable recipients to experiment, with it and port it. It is not guaranteed
to be
bug free although it has been extensively tested with all the facilities which
the ASSA testbench implementation
team have available.
The ANSA testbench is not supported as a warrantied
software product and
any or all parts of the testbench may change in future releases.
ANSA will
continue to evolve and these changes will be reflected in the design of the
testbench.
If you experience any trouble with porting or using the testbench please
contact the ANSA team. The ANSX team wish to be informed of all problems
and difficulties encountered
and within the constraints
of the project, will
give advice on how to deal with them.
The ANSA team will be pleased to receive extensions,
improvements,
new
ports or additional
services for incorporation
in future releases
of the
ARM XI, 12 / 8 (Release 01.01)
Installation
testbench. The most convenient form for supplying code changes to us is as
conditionally compilable sources in one of the following machine readable
forms, listed in order of preference:
HP 1” cartridge tape
SUN+” cartridge tape
electronic mail
5$” floppy
3” magnetic tape
- tar format
- tar format
- see cover sheet for addresses
- PC-DOS format ASCII file
- tar format
ANSA cannot accept any code with IPR or license restrictions or fees.
originators copyright will be attributed on all contributed code.
12.2
The
MSDOS
The ANSA testbench has been successfully ported to the IBM+ PC running
MSDO$. This appendix describes the requisite hardware and software, the
build procedure, test procedures, and limitations to the PC port.
12.2.1
Kequisite
hardware
and software
Hardware:
)
IBM PC (or PC clone) with 640K RAM
b
high density 5+” floppy drive (1.2 Mbyte) and hard disk with at least
3.5Mbytes of free space
)
network interface (see below)
Software:
D
MSDOS ~3.0 or later
B
Microsoft C compiler, ~4.0 or later
)
PUTCP ~2.02 for each target system
b
PCYTCP Development Kit ~2.02 for a system upon which the testbench
programs will be built
The choice of network hardware is dictated by those interfaces supported by
the PCPTCP package. They are shown in Table 12-1 below.
The network software and documentation may be obtained by contacting
‘1H.Mis a trademark of International Business Machines
iW3DOS is a trademark of Microsoft, Inc.
ARM XI, 12 / 9 (Release 01.01)
ANSA
Table 12-l: PCM‘CP
Reference
Manual
supported
network
interfaces
FTP Software, Inc.
P.O. Box 150
Kendall Square Branch
Boston, MA 02142
UNITEDSTATESOFAMERICA
12.2.2
Preparation
for installation
The following build procedure has worked successfully on the PC system at
ANSA. It assumes that you have booted RISDOSfrom the C: disk, and that you
have a high density 5$” floppy drive (1.2 MByte) for device A:. Any other
hardware configuration will necessitate major changes to all batch files and
makefiles.
When installing the C compiler and the PCiTCPDevelopment Kit, be sure to
install the Large Memory Model libraries, as the testbench build procedure
references these.
The build of the system at ANSA occurred under the following environment:
C:\> SET
COMSPEC=C:\COMMAND.COM
PATH=.;C:\PCTCP;C:\BIN;C:\UTILS
TEMP=C:\TEMP
PROMPT=$p$g
INCLUDE=C:\DEVKIT\INCLUDE;C:\INCLUDE
LIB=C:\DEVKIT\NETMSC4.0;C:\LIB
TMP=C:\
ARM XI, 12 / 10 (Release 01.01)
Installation
C:\>
Of these settings, four are critical to the successful building of the software:
D
having \BIN in the search path is necessary for the Microsoft C utilities
to be successfully executed; the WTILS directory is where the standard
MSDOS utilities (like COPY) are found on our system
the value of INCLUDE guarantees that the C compiler will search for
#include files in the include directory provided with the PUTCP
development kit and the include directories provided with the Microsoft
C compiler
)
b
the value for LIB guarantees that the requisite libraries needed to build
the applications will be found
b
the value for TMP is needed by the C compiler for building temporary
files
The parsers for the preprocessor and stub compiler are provided in C form;
the yacc grammars have already been processed using a public-domain
parser generator named bison'.These parsers include cstdio. h>. If the user
code provided with the grammar also includes <std i o. h>,a compile error will
occur. Since both of these grammars will exhibit the above error, it is
necessary that the distributed <std io . h> be modified as follows:
lifndef STD10
#define STD10
<distributed version of <stdio.h>>
#endif
12.2.3
Installation
procedure
To build the testbench, execute the following steps:
1.
Load the floppy disk into the A: drive
2.
CD\
3.
COPY A:INSTALL.BAT
.
4.
INSTALL
5.
CD \ANSA
6.
ANSABLD <TradingHostName> [y/n]
You must provide the name of the trading host as the first parameter of the
invocation to ANSABLD. The optional second parameter determines whether
intermediate files are deleted as the procedure proceeds. The completed
system consumes 3.4 Mbytes of disk space if the intermediate files are not
deleted, 2.6 Mbytes if they are.
‘bison is publicly-available
from the Free Software
Foundation
(GNU)
ARM XI, 12 / 11 (Release 01.01)
ANSA Reference Manual
Installation
12.2.4
tests
The installation script builds a number of test programs. All of the examples
below assume that your current working directory is \ANSA and that you have
started the trader and relevant server program on a UNIX host with which
the PC can communicate.
Note that the PC implementation
uses UDP only for
conveying REX packets, and assumes the standard port numbers as described
.
in section A.3 above.
12.2.4.1
REX and interpreter
The most basic test exercises
this, do the following:
test
the interpreter
and REX in isolation.
To run
src\test\callclient -ilOO OtherHost
This will repeatedly
issue REX calls and collect the replies reporting the
elapsed time and buffer sizes every 100 calls; the calls are sent to the server
running on OtherHost. You can change the number of iterations by altering
the number in the -i flag above.
By default, the call cl ient test runs endlessly.
Use the
-p<# of passes
option to cause it to terminate
12.2.4.2
Exercising
after < # of passes > .
the trader
Three tests which use the trader can be performed.
When the trader starts up, it registers itself as the exporter of two
additional services: TrCtxt and TrType.
The following commands
should yield information on these two service offers:
src\trader\trlook TrCtxt /
src\trader\trlook TrType /
The trsearch command causes information
on all offers matching
type specified in the nominated trading scope to be returned.
the
src\trader\trsearch ansa /
will cause information about all known offers to be displayed
types are sub-types of type ansa).
Next launch a number of Lookup requests at the trader,
of the elapsed time. This is done as follows:
(since all
keeping
track
src\trader\trtest
This program will request the offer information
on the TrCtxt offer
1000 times, and prints summary statistics of the performance
upon
completion.
For those who truly want to exercise the trader, trtest
ARM XI, 12 / 12 (Release 01.01)
Installation
takes an optional argument which is the number of times the 1000
requests should be attempted.
12.2.4.3
The Echo service
The simplest of the example services provided with the distribution is an
Echo service. This service is provided with three client programs:
client
simply reads each line from its standard input, invokes the Echo
function of the Echo server, and prints the echoed line on the
standard output.
techo
invokes the Echo function of the Echo server with a fixed size
buffer of characters a given number of times. Upon completion,
summary statistics about the transfer rate are displayed.
tsink
invokes the Sink function of the Echo server with a fixed size
buffer of characters a given number of times. Upon completion,
summary statistics about the transfer rate are displayed.
The following
previously:
command lines will exercise
src\Echo\client <ANSABLD.BAT
fc t.out ANSABLD.BAT
de1 t.out
src\Echo\techo -bl -nlOO
src\Echo\techo -blO -nlOO
src\Echo\techo -blOO -nlOO
src\Echo\techo -blOOO -nlOO
src\Echo\tsink -bl -nlOO
src\Echo\tsink -blD -nlOO
src\Echo\tsink -blOO -nlOO
src\Echo\tsink -blOOO -nlOO
the Echo
server started
>t.out
For both techo and tsink,you may optionally specify the name of a specific
host upon which the service is active with a command of the form:
src\Echo\techo -bl -nlOO HostName
12.2.4.4
The Sample service
The Sample service is provided to illustrate an interface specification with
multiple operations. One of the operations returns multiple results, another
takes no arguments, while the third returns no results. The client simply
invokes each operation 1000 times, printing the results from the two
operations which return results on the standard output. The following
commands are suggested for exercising the client:
ARM XI, 12 / 13 (Release 01.01)
ANSA
Reference Manual
’
src\Sample\client >t.out
more <t.out
de1 t.out
12.2.4.5
The Netinfo service
The Netinfo service is provided as an example of a non-trivial application of
the ANSA testbench.
Each UNIX system which supports
the socket
abstraction for interfacing to the TCPILDPIIP
family of protocols provides a set
of library routines which permit the programmer to determine information
about hosts, networks, protocols, and services. The usual implementation
of
these library routines is to read the appropriate information
from a set of
distinguished
files which are stored in /etc, returning to the caller a pointer
to some volatile data structures which have been loaded with the appropriate
information.
One complication of this particular implementation
style is the
necessity to keep multiple copies of the distinguished
files consistent.
The
Netinfo service is a simple implementation
of a name service
which
eliminates this consistency requirement.
Netinfo
provides
an RPC interface
to the routines
gethostbynameo,
getnetbyname(),getprotobyname(), and getservbynameo. The return results
from the remote procedure calls are discriminated
unions (specified as
CHOICE's)in which the full data structure is returned only if the lookup on the
server host was successful. The specification and the client programs can be
consulted for more information.
Four client programs are provided, each one
exercising a different operation in the interface.
The following command
lines should result in useful output from the client programs:
src\Netinfo\hclient
src\Netinfo\nclient
src\Netinfo\pclient
src\Netinfo\sclient
12.2.4.6
SomeHostName
arpa
udp
tcp ftp
The test1 service
This service is exactly the one described
The client program can be invoked as:
in section
12 1.3.4 of this manual.
src\testl\client 1 2 3 4 5
12.2.5
PC limitations
The PC makes a reasonable ASSA client machine. Due to the masking of ‘C
interrupts when a program is using the network software, it does not make a
particularly good server machine.
You will often have to reboot the system
to terminate a server program, with the net effect of leaving a stale export
offer in the trader’s database. This stale offer can be removed the next time
the system is booted if the following command is added to the I\KTOEXEC RAT
file after the network software has been started:
ARM XI, 12 / 14 (Release 01.01)
Installation
C:\ANSA\SRC\TRADER\DOSPURGE
Because of the hardware architecture of the IBM PC,fragmented buffers are
limited to a maximum size of 64Kbytes. Attempts to allocate larger buffers
when sending or receiving will fail. This limit is imposed because there is no
portable or standard way of addressing larger regions of contiguous memory
on an IBLMPC. Users of the PC testbench who have a solution to this problem
which is portable - i.e. will not cause inefficiency or obscure the source code
for other users - and is also standard i.e. will work on many ANSI compilers,
should submit it to ANSA for consideration as a part of a future release.
This port was completed to give collaborators an opportunity to build ANSA
clients in the PC environment. There may be some incipient bugs remaining
in the PC release, and we will attempt to fix any brought to our attention if
the bug report is accompanied by test programs which easily reproduce the
problem.
ARM XI, 12 / 15 (Release 01.01)

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project