home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 418.lha / OdinLibrary_v1.11 / odin.doc < prev    next >
Text File  |  1990-09-01  |  11KB  |  335 lines
  1. odin.doc, version 1.11, 13-Jul-90, Release 1
  2. Created 3-Jul-90 by Peter Oerbaek
  3.  
  4.                       Documentation for odin.library.
  5.  
  6.  
  7.    The main intention of this library is to provide an easier and more
  8. elaborate support for the multitasking capabilities of the Amiga. The func-
  9. tions are inspired by Linda, an extension-language to C and other
  10. languages, which provides a simple yet efficient multitasking/
  11. multiprocessing API.
  12.  
  13.    The central concept in odin.library is that of the envelope. An envelope
  14. is used to pass information between processes, and they are used to hold
  15. information residing in e-space. In C an envelope is a structure that
  16. begins with the Envelope structure defined in odin.h.
  17.  
  18.    There's no restrictions on the contents of an envelope, the contents being
  19. whatever comes after the Envelope-structure. The contents need not be
  20. contigous in memory. You can specify a C-function to serve as a copying-
  21. routine for each envelope.
  22.  
  23.    The e-space is an abstact storage containing envelopes and their contents.
  24. Envelopes are identified by a name, ie. a null-terminated ASCII string.
  25. Envelopes can be put into and retrieved from e-space via the name.
  26. E-space can contain many envelopes with the same name. Envelopes with the
  27. same name will be retrieved in the same order as they have been inserted
  28. into e-space, forming a queue.
  29.  
  30.    Two envelopes match if their names are equal.
  31.  
  32.    To prevent two different programs from unintentional interference with
  33. each others envelopes a naming convention should be applied. My suggestion
  34. is to name envelopes intended for private use within some internal task
  35. like this: "<ProgramName>:<envelopename>" (this is not used in my
  36. examples...). 
  37.  
  38.    Functions for general envelope-management are: CreateEnvelope(),
  39. InitEnvelope() and DisposeEnvelope(). To put envelopes into e-space use:
  40. Out(),CopyOut() or OutEmptyEnvelope(). You can wait for an envelope to
  41. appear in e-space with: In(), Rd() and AwaitNamedEnvelope(). You can also
  42. poll for the existence of envelopes in e-space with: Inp(), Rdp() and
  43. PollNamedEnvelope().
  44.  
  45.    New tasks and processes can be launched by the Eval() function. Eval()
  46. provides a simple, yet powerful way to transfer arguments to the new task/
  47. process, and a way to determine when the new task/process is finished.
  48.  
  49.    There are also two lower-level functions for creating tasks/processes:
  50. StartTask() and StartProcess().
  51.  
  52. ------------------------------------------------------------------------
  53.                              Function summary
  54.                              -----------------
  55. ------------------------------------------------------------------------
  56.  
  57. Envelope *InitEnvelope(env,name,len,copyfunc)
  58.    D0                   A1  A0   D0   A2
  59. Envelope *env;
  60. char     *name;
  61. ULONG    len;
  62. Envelope *(*copyfunc)();
  63.  
  64.    Initializes env with the name 'name', length of envelope+contents in bytes:
  65.    'len', and sets the copyfunc for the envelope to copyfunc.
  66.    The Eval() function (e_proc) is not touched.
  67.    Returns the newly initialized envelope.
  68.    Use the macro NoCopyFunc to specify that the e_copyfunc should be init-
  69.    ialized to NULL.
  70.  
  71.    SEE ALSO
  72.       CreateEnvelope(), Rd().
  73.  
  74. ------------------------------------------------------------------------
  75.  
  76. Envelope *In(env)
  77.    D0         A1
  78. Envelope *env;
  79.  
  80.    Tries to extract an envelope from e-space with a matching name. If no
  81.    envelopes in e-space matches, the caller is put to sleep until a
  82.    matching envelope is entered into e-space. The matching envelope is
  83.    taken out of e-space and returned. No copying is done.
  84.  
  85.    SEE ALSO
  86.       Rd(), Inp(), AwaitNamedEnvelope().
  87.  
  88. ------------------------------------------------------------------------
  89.  
  90. Envelope *Rd(env)
  91.    D0         A1
  92. Envelope *env;
  93.  
  94.    Works like In(), but copies the envelope from e-space to env. If 
  95.    e_copyfunc of the envelope to be extracted is non-NULL, that function
  96.    is used to copy envelope and contents. If copyfunc is NULL the envelope
  97.    and contents just after it are copied byte for byte to the location
  98.    given by env. No envelope is taken out of e-space.
  99.    The copyfunc feature allows complex structures to be copied (eg. binary
  100.    trees). A copyfunc should have the following declaration:
  101.  
  102.    Envelope *copy_func(source,target)
  103.    Envelope *source,*target;
  104.    {  ....
  105.       return target;
  106.    }
  107.  
  108.    The target-pointer should be returned.
  109.    The copyfunc should be made very fast because e-space is locked while
  110.    the copying is being done, preventing other tasks from altering e-space.
  111.    Rd() returns a pointer to the copy.
  112.  
  113.    SEE ALSO
  114.       In(), Rdp().
  115.  
  116. ------------------------------------------------------------------------
  117.  
  118. void Out(env)
  119.          A1
  120. Envelope *env;
  121.  
  122.    Puts env into e-space. This is a non-copying operation, so it is
  123.    possible, although NOT recommended, to alter the contents of the
  124.    envelope while it is in e-space.
  125.  
  126.    SEE ALSO
  127.       CopyOut(), OutEmptyEnvelope().
  128.  
  129. ------------------------------------------------------------------------
  130.  
  131. void CopyOut(env)
  132.               A1
  133. Envelope *env;
  134.  
  135.    Puts a copy of env into e-space. If env->e_copyfunc is non-NULL this
  136.    is used to copy the envelope and contents to a newly created envelope
  137.    of the same size as env. If e_copyfunc is NULL the envelope is copied
  138.    byte for byte.
  139.    Use this to put multiple copies of an envelope into e-space.
  140.  
  141.    SEE ALSO
  142.       Rd(), Out(), OutEmptyEnvelope().
  143.  
  144. ------------------------------------------------------------------------
  145.  
  146. struct Task *Eval(env,pri,stacksize,et)
  147.         D0         A1  D0    D1     D2
  148. Envelope *env;
  149. long pri,et;
  150. ULONG stacksize;
  151.  
  152.    Eval() creates a new Process or Task (by StartProcess() or StartTask()),
  153.    determined by the 'et' parameter. If this parameter is EVAL_PROCESS
  154.    a process is started, and if it is EVAL_TASK a task is started.
  155.    Eval() passes the envelope 'env' to the new process/task without any
  156.    copying. The body of the process is the C-function in env->e_proc.
  157.    This should have the following declaration:
  158.  
  159.    Envelope *new_process(passed_env)
  160.    Envelope *passed_env;
  161.    { ... }
  162.  
  163.    The stacksize of the new process/task is set to 'stacksize' bytes, and
  164.    the process/task gets the priority 'pri'.
  165.    The name of the new process becomes the name of the passed envelope.
  166.  
  167.    When the body-function returns an envelope, this envelope is put into
  168.    e-space with an Out()-call just before the task/process dies. This can
  169.    be used for syncronization between tasks. Be warned though! The system
  170.    will panic if the function does in fact NOT return an envelope.
  171.    If NULL is returned from the body-function, the process/task just dies,
  172.    and nothing is added to e-space.
  173.  
  174.    Eval() carries all registers over to the new task/process except
  175.    A7 and A2!.
  176.  
  177.    Eval() returns a pointer to the Task structure of the new process/task,
  178.    or NULL if something goes wrong.
  179.  
  180.    SEE ALSO
  181.       CreateProcess(), Out(), CreateTask().
  182.  
  183. ------------------------------------------------------------------------
  184.  
  185. Envelope *Inp(env)
  186.    D0          A1
  187. Envelope *env;
  188.  
  189.    Works like In(), but instead of waiting when no matching envelope exists
  190.    in e-space, NULL is returned immediately. This corresponds to a kind of
  191.    polling.
  192.  
  193.    SEE ALSO
  194.       In(), Rdp(), PollNamedEnvelope().
  195.  
  196. ------------------------------------------------------------------------
  197.  
  198. Envelope *Rdp(env)
  199.    D0         A1
  200. Envelope *env;
  201.  
  202.    Works like Rd(), but doesn't wait for a matching envelope, instead NULL
  203.    is returned.
  204.  
  205.    SEE ALSO
  206.       Inp(), Rd().
  207.  
  208. ------------------------------------------------------------------------
  209.  
  210. struct Task *StartTask(proc,name,pri,stacksize)
  211.      D0                 A0   A1   D0   D1
  212. void (*proc)();
  213. char *name;
  214. long pri;
  215. ULONG stacksize;  /* stack size in bytes, must be even */
  216.  
  217.    This allocates a stack, and a Task structure, and starts a new task to 
  218.    execute proc. All registers except the stackpointer are carried over to
  219.    the new task. This is necessary since many compilers use register- 
  220.    relative addressing to access global variables.
  221.    When the procedure returns, the task dies.
  222.    A pointer to the newly created Task is returned, or NULL if something
  223.    goes wrong.
  224.  
  225.    SEE ALSO
  226.       StartProcess(), Eval().
  227.  
  228. ------------------------------------------------------------------------
  229.  
  230. struct Process *StartProcess(proc,name,pri,stacksize)
  231.           D0                  A0   A1  D0     D1
  232. void (*proc)();
  233. char *name;
  234. long pri;
  235. ULONG stacksize;  /* size is in bytes */
  236.  
  237.    As above, just creates a Process instead.
  238.    Proc does not have to be at the start of a segment or lie on a 4-byte
  239.    boundary.
  240.    The process structure and stack are automatically freed when the process
  241.    dies by returning or calling Exit(). The code is NOT unloaded.
  242.    NB. Returns a pointer to the real Process-struct ie. not the messageport
  243.        in it.
  244.  
  245.    SEE ALSO
  246.       StartTask(), Eval().
  247.  
  248. ------------------------------------------------------------------------
  249.  
  250. Envelope *AwaitNamedEnvelope(name)
  251.   D0                          A0
  252. char *name;
  253.  
  254.    AwaitNamedEnvelope creates a temporary envelope with the name 'name',
  255.    and waits for a matching envelope to appear in e-space. When and if a
  256.    matching envelope appears, it is taken out of e-space and returned.
  257.    The temporary envelope is disposed of.
  258.    Use this instead of In().
  259.  
  260.    SEE ALSO
  261.       In().
  262.  
  263. ------------------------------------------------------------------------
  264.  
  265. Envelope *PollNamedEnvelope(name)
  266.   D0                         A0
  267. char *name;
  268.  
  269.    PollNamedEnvelope() checks if an envelope with the given name exists
  270.    in e-space, and if so, it takes it out of e-space and returns it. If
  271.    no envelope with the given name exists in e-space NULL is returned 
  272.    immediately.
  273.    This is actually a combination of InitEnvelope() and Inp().
  274.  
  275.    SEE ALSO
  276.       Inp().
  277.  
  278. ------------------------------------------------------------------------
  279.  
  280. void OutEmptyEnvelope(name)
  281.                        A0
  282. char *name;
  283.  
  284.    OutEmptyEnvelope() creates an empty envelope, with CreateEnvelope(),
  285.    gives it the name 'name' and puts it into e-space with Out().
  286.    This could be used for simple synchronization.
  287.  
  288.    SEE ALSO
  289.       Out().
  290.  
  291. ------------------------------------------------------------------------
  292.  
  293. Envelope *CreateEnvelope(name,size)
  294.    D0                     A0   D0
  295. char *name;
  296. ULONG size;
  297.  
  298.    CreateEnvelope() creates a new envelope using AllocMem(). Size is the
  299.    byte-size of the envelope+contents. Eg.
  300.  
  301.    struct FilledEnv {
  302.       Envelope env;
  303.       struct Image img;
  304.    };
  305.    struct FilledEnv *fe;
  306.    ....
  307.    fe = (struct FilledEnv *)CreateEnvelope("imageenvelope",
  308.                                            (long)sizeof(struct FilledEnv));
  309.  
  310.    The new envelope is initialized with InitEnvelope() to have the given
  311.    length, and no copyfunc or proc.
  312.    If there is not enough memory for the creation, NULL is returned.
  313.  
  314.    SEE ALSO
  315.       DisposeEnvelope(), InitEnvelope().
  316.  
  317. ------------------------------------------------------------------------
  318.  
  319. void DisposeEnvelope(env)
  320.                       A1
  321. Envelope *env;
  322.  
  323.    DisposeEnvelope() frees the space taken up by the envelope, by using
  324.    FreeMem().
  325.    If NULL is passed to this routine nothing is done. This can be used
  326.    eg. like this:
  327.  
  328.    ....
  329.    do { DisposeEnvelope(p = PollNamedEnvelope(name)) } while(p);
  330.    ....
  331.  
  332.    SEE ALSO
  333.       CreateEnvelope().
  334.  
  335.