Linda API (Version 1.03)
========================

1.	Creating a Linda-client object (JAVA only)

	Description:

		Create a Linda-client object to a Linda-server.
		Returns an Linda-client object.

	Java API (constructor):

		LindaClient()

		Create a Java Linda-client object which will be used to
		connect to a Linda-server. The host and port of
		the Linda-server will have to be specified when
		making the connection.

		LindaClient(String host,int port)

		Creates a Java Linda-client object to the Linda-server at
		the specified host and port.

2.	Connecting to a Linda-server

	Description:

		Connect to a specific Linda-server.

	Prolog API:

		linda_client(Host:Port)

		Connect to the specified Linda-server at the "Host"
		and "Port". "Host" is an atom and "Port" is an integer.
		The predicate fails if the connection cannot be made.

	Java API (object method):

		void connect() throws SocketException,
				UnknownHostException,
				IOException

		Connects to the Linda-server specified by the "host"
		and "port" parameters when the Linda-client object is
		created.

		void connect(String host,int port) throws SocketException,
						UnknownHostException,
						IOException

		Connects to the Linda-server specified by "host" and "port".

		This method throws an UnknownHostException if the host is
		unknown. It throws an IOException if there is any I/O error,
		or a SocketException if it is a general socket error.

3.	Disconnecting from the Linda-server

	Description:

		Disconnect from the current Linda-server.

	Prolog API:

		close_client

		Disconnect from the current Linda-server.
		The predicate fails on any error.

	Java API (object method):

		void disconnect() throws IOException

		Disconnect from the connected Linda-server.
		It throws an IOException on any error.


4.	Put a tuple into the Linda-server

	Description:

		Put a Prolog term into the Linda-server's tuple space.

	Prolog API:

		out(?Term)

		"Term" s a Prolog term which may contain variables.
		This predicate fails on any error.

	Java API (object method):

		void out(String term) throws IOException

		"term" is a Java string following the syntax of
		a valid Prolog term and representing the term
		to be put into the Linda-server.
		This method throws an IOException on any error. On
		successful operation, it returns nothing.

5.	Get a tuple from the Linda-server with blocking

	Description:

		Get a Prolog term from the Linda-server's tuple space
		with blocking.
		If more than one matching tuple is found, only one
		is returned. The matching tuple is removed from the
		server upon successful matching.
		If there is no matching tuple in the server, the
		operation will block until a match is found.

	Prolog API:

		in(?Template)

		"Template" is Prolog term which may contain variables.
		This predicate blocks until a matching term is found
		in the Linda-server.

		in(?Templates,-Tuple)

		"Templates" is a list of matching templates. A tuple
		matching any one of these templates is returned.

	Java API (object method):

		String in(String template) throws IOException,
				InterruptedIOException

		"template" is a Java string representing the
		tuple matching template in the Prolog syntax.
		It throws an IOException on any error.
		This method blocks until a matching tuple is found,
		which is returned as a Java string.

		*** It should not return an InterruptedIOException.

6.	Get a tuple from the Linda-server without blocking

	Description:

		Get a Prolog term from the Linda-server's tuple space
		without blocking. Upon successful matching, the tuple
		is removed from the server.

	Prolog API:

		in_noblock(?Template)

		"Template" is a Prolog term which may contain variables.
		If there is a matching tuple in the server, the predicate
		succeeds and "Template" is unified with the matching tuple.
		If there is no matching tuple, the predicate does not
		block but fails after waiting for a time-out period.
		The time-out value is set by the "linda_timeout/2" API.

	Java API (object method):

		String in_noblock(String template) throws IOException

		"template" is a Java string representing the tuple
		matching template in Prolog syntax.
		If there is a matching tuple in the server, it is
		returned as a Java string.
		If no matching tuple is found, the operation waits for a
		time-out and returns "null".
		This method throws an IOException on any error.
		The time-out value is set by the "set_timeout" API.

7.	Check if a tuple is in the tuple space with blocking

	Description:

		Check if a matching tuple is in the server's tuple space
		with blocking.
		The matching tuple is not removed from the server and
		the operation blocks until a match is found.

	Prolog API:

		rd(?Template)

		"Template" is a Prolog term which may contain variables.
		On successful operation, the matching tuple is unified
		with "Template" but it is not removed from the server. 
		The predicate blocks until a match is found.

		rd(?Templates,-Tuple)

		Similar to "rd/1" but allows the use of a list of
		matching templates instead of just one.

	Java API (object method):

		String rd(String template) throws IOException,
					InterruptedIOException

		The Java string "template" represents the tuple matching
		template in the Prolog term syntax. This method blocks
		until a match is found.
		On successful matching, the matching tuple is returned
		as a Java string but it is not removed from the server.
		The method throws an IOException on any error.

		*** It should not throw an InterruptedIOException.


8.	Check if a tuple is in the tuple space without blocking

	Description:

		Check if a matching tuple is in the server's tuple space
		without blocking. The matching tuple is not removed
		from the server.

	Prolog API:

		rd_noblock(?Template)

		"Template" is a Prolog term which may contain variables.
		On successful operation, the matching tuple is unified
		with "Template" and is not removed from the server.
		The predicate fails if no match can be found within
		the time-out period.
		The time-out value is set by the "linda_timeout/2" API.

	Java API (object method):

		String rd_noblock(String template) throws IOException

		"template" is the matching template in a Java string.
		On successful operation, the matching tuple is returned
		as a Java string.
		If no matching tuple can be found without the time-out
		period, the method returns "null".
		The time-out value is set by the "set_timeout" API.

9.	Set time-out

	Description:

		Set the timeout value of non-blocking operations.

	Prolog API:

		linda_timeout(-Old,?New)

		"New" is the new timeout value in the form
		"second:millisecond" where both values are integers.
		If "New" is not fully instantiated, it will be unified
		with the existing timeout value.
		"Old" is instantiated to the old timeout value.

	Java API (object method):

		boolean set_timeout(int millisecond)

		Set the timeout value in milli-second.
		It returns true when success or false when fail.

10.	Set protocol

	Description:

		Sets the Linda protocol to be used by this Linda-client.
		The Linda-server supports both "p" and "f" Linda protocol.
		The Prolog Linda-client also supports both protocols
		but the Java Linda-client can only support the "p" protocol.

	Prolog API:

		***	There is no API for the Prolog client yet.
			It is set by the "protocol/1" clause.

	Java API (object method):

		boolean set_protocol(char protocol)

		"protocol" is either "p" or "f" in the Java "char"
		data type. (Note: It is not a "Character" object.)
		Currently, only "p" is supported.
		This method returns true if success or false if fail.