Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!wuarchive!uunet!tnc!m0154
From: m0154@tnc.UUCP (GUY GARNETT)
Newsgroups: comp.sys.amiga.programmer
Subject: An Amiga Conversion Facility (2 of 3) LONG!
Message-ID: <791@tnc.UUCP>
Date: 10 Apr 91 19:43:54 GMT
References: <790@tnc.UUCP>
Reply-To: m0154@tnc.UUCP (GUY GARNETT)
Organization: The Next Challenge, Fairfax, Va.
Lines: 201


[if you don't want to to read this long thing, hit "n" now!]
 
           A Conversion Utility for the Amiga (Part 2 of ?)
            (A modest proposal from "Wildstar"; 200 lines)
              - this document is freely distributable -
 
4) Details
 
  Application Interface:  A client application communicates with the
conversion facility via standard Exec messages (but see the
discussion of IPC, below).  In order to make conversion requests, the
application will need a message port with a unique name.  Each
request is a separate message, and is sent to the convertor client
message port "ConvClientPort".  The convertor will copy the request
into its queue, and reply the message (which can then be freed or
re-used as needed).  When the requested function has completed, the
convertor will verify that the client's message port still exists,
and if so, it will send a results message.  The client should reply
this message as soon as it is done with it.  If the client message
port does not exist, the convertor will assume that the client has
exited, and will discard the results.
 
  Possible Requests: A client can request several functions of the
convertor.  The client could request a data conversion (convert this
data from a format to another format; for example, from IFFILBM to
EPSF), recognition (for example, is this valid IFFILBM data?),
identification (what is this data?), cancellation (cancel all pending
requests), convertor status (list clients, requests queued, in
progress, and completed, and other information), module status (list
modules, source and target formats, and lock status), lock a module
(ensure that a given module is loaded and stays loaded), and unlock a
module (remove a module lock).  The last four request types can be
used to implement a monitor for the conversion utility, or by
applications to manage the convertor.
 
5) More Details
 
  Module Functions:  Modules need to implement a number of control
functions in order to operate properly within the conversion
facility.  All modules must implement a status function (which
returns information about the current status ofthe module), a cancel
function (which cancels the current operation, if any), and an exit
function (which requests that the module exit, if possible).
  Each module can optionally implement functions for some or all of
the following data operations: convert (sorce data format to target
data format; it is assumed that this is the primary function of most
modules), recognise (a data format; determines whether or not the
data is in a specfied format), and identify (determines the format of
data whose format is unknown).  It is not necessary to implement all
(or even implement any) of the operations for a module to function
properly (but a module which implements no operations is unlikely to
be used).  The convertor will request only one operation at a time
from each module (multiple requests will be queued internally by the
convertor) to simplify module logic.
 
  Module Installation:  Modules are program (tool) files, stored in a
logical device CONVMOD:.  Any legal file name is a legal module name,
although it is suggested that it be mnemonic for the function of the
module (like "PS-to-IFF").  It is also suggested that they be
provided with icon (.info file) for two reasons:  Ease of
installation by the end user (just drag this icon into your
"Conversions" drawer) and to provide the convertor with additional
information.
 
  Tool Types:  If an icon is present for a given module, the tool
types can be used to provide the convertor with information about the
capabilities of the module.  The following tool types could be used:
VERSION (to specify the version of this module for the user's
reference; for example, VERSION=1.10), SOURCE (to specify the source
formats that this module can translate, multiple formats can be
separated by a vertical bar character; for example,
SOURCE=IFFILBM|IMAGE|BITMAP), TARGET (to specify the target formats
produced by this module; for example, TARGET=POSTSCRIPT|EPSF), and
FUNCTION string (to specify the data operation functions supported by
the module; for example, FUNCTION=CONVERT|RECOGNISE).  Other tool
types should be ignored by the convertor.
 
  Module Initialization:  When a module is executed, it should
initialize itself, and create a message port for receiving requests. 
This port should have a unique name (multiple copies of a given
module can be loaded, and if so, a mechanism should be provided to
generate unique names).  When it is ready to begin receiving function
requests, it should send a message to the convertor module, via its
module message port "ConvModulePort".  The message should contain the
module's name (the name of a message port to which the convertor can
send module requests), and version, source, target, and function
information (as above).  If the information provided by scanning the
tool types differs from the module's startup message, the convertor
should assume that the tool types are incorrect for this module. This
may result in the convertor sending an immediate termination request
to the module, and continuing its module search.  The convertor will
copy information from this startup message, and will reply it as soon
as possible, so that it can be freed or reused.
 
  Request Interface:  The convertor will request operations by the
module with exec messages.  Each message will request a module
function, and should be replied as soon as the convertor has copied
the pertinent information.  The convertor ensures that no more
request messages will be sent until the current one is replied.  When
the operation is complete, the convertor should send another message
to "ConvModulePort" with the results.  If "ConvModulePort" should
dissappear (it shouldn't) the module would be perfectly justified in
assuming that everyone else left and didn't tell it (discard the
results and terminate the module).  The convertor will maintain an
internal queue of pending requests for a given module (and may load
multiple copies of a given module, if the situation warrants). 
However, each module should periodically check its message port while
processing a request.  The convertor may request that the module
terminate, cancel the current request, or provide status information.
 
6) Still More Details
 
  Convertor:  The convertor itself should be started before any
modules are executed (if it is not, and a client program "manually"
starts some modules, the convertor may not be aware of those modules,
and may load additional copies, wasting memory).  The convertor
maintains two message ports, "ConvClientPort" (for receiving requests
by client modules) and "ConvModulePort" (for receiving startup
messages and result messages from modules).
 
  Internals:  The convertor should maintain a list of all currently
loaded modules, their capabilities, and their current status.  It
should also maintain queues of requests destined for those modules, a
list of currently-known clients, and a list of pending requests
(pending a startup message from a module, that is).  The convertor is
responsible for starting and terminating modules (so that it can
implement the module lock and unlock features).  The convertor may
optionally use this information to manage its memory usage by
terminating currently unused modules (and to retain unused modules
which are likely to be needed again).  The convertor may also cache
information (gleaned from tool types, or from prior executions of the
module) about modules which are not currently loaded, if provision is
made for invalidating or updating this data (for example, when the
user installs a new module in the middle ofa session).
 
  Requests:  Requests from clients are queued at the convertor's
client message port, and are processed in the order that they are
received from that port.  Therefore, it may be possible to use the
message priority can be used to implement a "rush" processing scheme.
(most clients should use a priority of 0, so that requests are
processed in first-in, first-out order).  As each request is
received, it becomes the current request, the client information is
added or updated in the client list, and the convertor searches for a
module to perform the request.
 
  Loading Modules:  When a module is loaded, the current request
(which, by definition, caused that module to be loaded), the search
status for that request, and related status information is placed on
a pending list.  The module will (hopefully) load and execute,
sending a startup message to the convertor's module message port.  As
startup messages are received, the module is added to the convertor's
module status lists, and the pending list is searched for the request
(or requests) which caused the module to be loaded.  If the convertor
determines that startup messages have been received from all modules
which have been requested, any pending requests are released to
continue with the search process.
 
  Searching:  When searching for a module to fufil a client request,
the convertor should use a four-phase search.  The search is
complete when a module which can fufil the current request (as
determined by that modules startup message) has been loaded.
  First, the convertor examines its list of currently-loaded modules. 
If one of them can fufil the current request, it is queued for
processing by that module.  If another request is on the pending list
(waiting for a module to load), the current request is also placed on
the pending list.  If neither of these conditions is true, the search
continues with the next step.
  Second, it should examine the tool types of all modules which have
icons.  Any modules whose tool types indicate that they can fufil the
current request are loaded.  If the module's startup message does not
confirm that it can fufil the request, the search continues (with
this step, or if all icons have been searched, with the next step).
  Third, modules without icons are loaded, one by one (with the
request being placed on the pending list each time).  If no modules
can be found to satisfy the request, the search proceeds the next
step.
  Fourth, modules with icons, but that were not loaded in the second
setp, are loaded (with the current request being placed on the
pending list each time).  If no modules can be found to satisfy the
request, the search fails (no module is available to convert  the
requested data).  This step is also optional, it can be selected by a
conversion facility option (perhaps by a switch on the convertor at
startup time).  If the fourth step is not enabled, then the search
ends after the third step.
  To avoid heavy disk and memory demands, as well as excessive
conversion time, it is recommended that all modules have an
assoicated icon file.
 
  Module Management:  It is quite possible for modules to be loaded
for wich there is no current need (either as a result of the search
process, or because it has no more requests to process).  Each time
the convertor loads a module, it should also check the list of
currently loaded modules.  If there are any which have never had a
request, it should terminate them (it is likely that they are the
result of a failed search).  The convertor should also consider
unloading modules which have been used in the past, but are currently
idle.
 
[to be continued ...]
Wildstar