========================================================
(C)1995 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information.)
========================================================

[1] What is a distributed pool?
-------------------------------

A distributed pool is a table maintenance utility which provides
various forms of tables with arbitrary keys and data. It has been
extensively used by experimental parallel application programs. Users
can ease programming efforts by using a distributed pool.
 
The original pool provided by PIMOS operating system of PIMs did not
run in parallel. All the data is managed by a single process.
Therefore, when data are accessed from many nodes at the same time,
network congestion and access latency become problematic. The
distributed pool is designed to solve these problems. The distributed
pool distributes the original pool to each node, and maintains the
coherence among copies cached to several original pools.

The distributed pool will alleviate load congestion, and improve data
access latency. Moreover, by dispersing the memory consumption at many
transaction nodes, the maximum capacity of the pool is greatly
expanded.

[2] Functions provided
----------------------

[2-1] User interface
--------------------
The following messages to the obtained stream (a logic variable) of
the cache process enables users to operate the distributed pool. (see
doc/manual.tex about how to obtain the stream.)

empty(Key, ^YorN)

Inquires whether the element with the key `Key' is in the pool. If
there is the element, `YorN' is unified with `yes'; otherwise, with
`no'.

put(Key, ?X, ^Status)

Adds a new element with the key `Key' in the pool, and its value is X.
If there is an element with the key `Key', returns `replaced', if not,
returns `added' in `Status'.

get_if_any(Key, ?X)

Removes an element with the key `Key' from the pool, and returns it in
`X' in a format of `{ ?value }'. The element disappears from the pool.
If there is no corresponding elements, returns `{}' in `X'.

carbon_copy(Key, ^O)

Refers to the element with the key `Key' in the pool, and returns it
in `O'.  The format of `O' is a list of values.  If there is no
corresponding elements, returns `[]' in `O'. 

get_if_any_and_put(Key, ^X, ?Y)

Removes an element with the key `Key' from the pool, if any, returns
it in `X' in a `{ ?value }' format.  Then, adds a new element `Y' in
the same location.  If there is no corresponding element, returns `{}'
in `X' and adds a new element `Y'. 

get_and_put_if_any(Key, ^X, ?Y, ^Y1)

Removes an element with the key `Key' from the pool, if any, returns
it in `X' in as `{ ?value }' format. Then, adds a new element `Y' in
the same location, and returns `{Y1}'. If there is no corresponding
element, returns `{}' in `X', and returns `{ ?Y }' in `Y1', though
nothing is done for the pool.

remove(Key, ^Status)

Deletes the element with the key `Key' from the pool.  If there are
already any elements with the key `Key' in the pool, returns `removed'
in `Status'. If not, returns `non_existent' in `Status'.

get_load_factor(^A)

Returns the hash table load factor `A' at the point the message is
received. The load factor indicates the ratio of the number of
entries in use to the total size of the hash table.  It is expressed
as a floating point number between 0.0 and 1.0.

get_average_chaining_length(^L)

Returns the average chain length `L' of element chains in the hash
table at the time the message is received.  Hash table collision is
processed by separate chaining. This results in elements with the same
hash value being connected in the same chain. The average chain length
indicates the average length of chains (of length 1 or more) existing
in the hash table. It is expressed as a floating point number greater
than or equal to 1.0.  When the hash table is empty, 0.0 is returned
for `L'.

[2-2] Some kinds of distributed pools 
-------------------------------------
Three kinds of distributed pools are provided for users. The 1),2)
types are categorized on difference of policies determining cache
coherency algorithm.

1) Distributed pool of a moving ownership type
2) Distributed pool of a fixed ownership type 
3) Distributed pool with a monitor on accessing data

Type 3) allows users to give information on data access. Users can 
tune up application programs by using it. Messages introduced in [2-1]
are classified according to whether they update the contents of a
distributed pool. A read type of messages does nothing to it.

$B!&(BThe number of a read type messages
$B!&(BThe number of a update type messages
$B!&(BThe number of miss hits of a read type 
$B!&(BThe number of miss hits of a update type 
$B!&(BThe number of a update type messages to shared data
$B!&(BThe number of replacement

[3] Execution Environment
-------------------------
Programs using a distributed pool run under PIMOS operating system of
PIMs.

[4] Install
-----------
 See INSTALL or INSTALL.j (in Japanese) for details.

[5] Documents
-------------
 Several documentations are provided for users in the ./doc directory.
 -------------------------------------------------------
  File name		Contents
 -------------------------------------------------------
  manual.tex	how to use a distributed pool 
  manual-j.tex	how to use a distributed pool (in Japanese)
  internal-j.texinternal data (in Japanese)
  ilps94.tex	a paper of the 1994 International Logic Programming
		Symposium (ILPS'94) workshop on Design &
		Implementation of Parallel Logic Programming Systems.
  fgcs94.tex	a paper of the International Symposium on Fifth
		Generation Computer System 1994 (FGCS'94).

[6] Bugs
--------

[7] Directories and files
-------------------------
Archive files contain the following direcotries and files.
 -------------------------------------------------------
  File name		Contents
 -------------------------------------------------------
  README	This file
  README.j	README (in Japanese)
  INSTALL	Installation guide
  INSTALL.j	Installation guide (in Japanese)
  COPYRIGHT	Terms and conditions for use of "ICOT Free Software"
  COPYRIGHT.j	Terms and conditions for use of "ICOT Free Software"
		(in Japanese)
  doc/		Documentation

  src/		Source files
    owner-migration/    Distributed pool of a moving ownership type
    owner-fixed/        Distributed pool of a fixed ownership type 
    access-info/        Distributed pool with a monitor on accessing data 

  obj/	 	Object files
    owner-migration/   *.sav 
    owner-fixed/       *.sav 
    access-info/       *.sav 

  test/		Sample programs

