liboaa.h File Reference

#include <unistd.h>
#include <libtrigger.h>
#include <libutils.h>

Go to the source code of this file.

Defines
#define	EXTERN   extern
#define	FALSE   0
#define	TRUE   1
#define	OAA_LIBRARY_VERSION   oaa_library_version_str;
#define	STREQ(str1, str2)   (strcmp((str1), (str2)) == 0)
#define	sleep_millis(n)   usleep((n)*1000L)
Functions
EXTERN int	oaa_Register (char *ConnectionId, char *AgentName, ICLTerm *Solvables)
	Once a comm link is established, either as a client to a Facilitator or as a server for other agents, oaa_Register will setup and registration information for this agent.
EXTERN void	oaa_Ready (int ShouldPrint)
	Changes the agent's 'open' status to 'ready', indicating that the agent is now ready to receive message.
EXTERN int	icl_Builtin (ICLTerm *goal)
EXTERN int	icl_BasicGoal (ICLTerm *goal)
	Test whether an expression is an ICL basic (non-compound) goal; that is, just a functor with 0 or more arguments.
EXTERN int	icl_GetParamValue (ICLTerm *Param, ICLTerm *ParamList, ICLTerm **Result)
	To get or test the value of a parameter that has a default, it is best to call icl_GetParamValue().
EXTERN int	icl_GetPermValue (ICLTerm *Perm, ICLTerm *PermList, ICLTerm **Result)
	To get or test the value of a parameter that has a default, it is best to call icl_GetPermValue().
EXTERN int	icl_ConvertSolvables (int toStandard, ICLTerm *ShorthandSolvables, ICLTerm **StandardSolvables)
	Convert between shorthand and standard forms of solvables list.
EXTERN int	oaa_Init (int argc, char *argv[])
	Must be called to init oaa parameters, such as argv and agrc.
EXTERN void	oaa_MainLoop (int ShouldPrint)
	The main event loop for the application.
EXTERN void	oaa_ProcessAllEvents ()
	To be called when the application that uses OAA has its own event loop.
EXTERN void	oaa_ProcessEvent (ICLTerm *Event, ICLTerm *Params)
	Interprets an incoming event.
EXTERN void	oaa_SetTimeout (double NSecs)
	Sets the timeout value used by oaa_GetEvent().
EXTERN void	oaa_GetEvent (ICLTerm **Event, ICLTerm **Params, int LowestPriority)
	Return the next event to execute.
EXTERN int	oaa_ValidateEvent (ICLTerm *E, ICLTerm **OkEvent)
	Check that an incoming lowlevel event should be processed.
EXTERN int	oaa_Interpret (ICLTerm *goal, ICLTerm *params, ICLTerm **solutions)
	Executes an incoming event Implements a simple meta-interpreter for executing complex goals.
EXTERN int	oaa_DelaySolution (ICLTerm *id)
	Requests that the current AppDoEvent not return solutions to the current goal until a later time.
EXTERN int	oaa_ReturnDelayedSolutions (ICLTerm *id, ICLTerm *solution_list)
	Returns the list of solutions for a delayed request.
EXTERN int	oaa_AddDelayedContextParams (ICLTerm *id, ICLTerm *params, ICLTerm **new_params)
	When a goal is delayed using oaa_DelaySolution(), incoming context parameters from the original request can not be automatically concatenated to outgoing oaa_Solve() requests.
EXTERN int	oaa_PostEvent (ICLTerm *contents, ICLTerm *params)
	Sends a low-level event to another agent.
EXTERN int	oaa_Version (ICLTerm *agent_id, ICLTerm **language, ICLTerm **version)
	Lookup the language and library version number for an agent.
EXTERN int	oaa_CanSolve (ICLTerm *goal, ICLTerm **kslist)
	Asks the Facilitator for a list of agents which could solve a Goal.
EXTERN int	oaa_Ping (ICLTerm *agent_addr, double time_limit, double *total_response_time)
	Tests whether a given agent is currently responding to requests.
EXTERN int	oaa_Declare (ICLTerm *solvable, ICLTerm *initial_common_perms, ICLTerm *initial_common_params, ICLTerm *initial_params, ICLTerm **declared_solvables)
	Declare solvables for a client or facilitator, and inform the parent if appropriate.
EXTERN int	oaa_DeclareData (ICLTerm *solv, ICLTerm *params, ICLTerm **declared_solvs)
	Declare data solvables for an agent.
EXTERN int	oaa_Undeclare (ICLTerm *solvable, ICLTerm *initial_params, ICLTerm **undeclared_solvables)
	Remove solvables from a client or facilitator, and inform the parent if appropriate.
EXTERN int	oaa_Redeclare (ICLTerm *initial_solvable, ICLTerm *initial_new_solvable, ICLTerm *initial_params)
	Replace a solvable on a client or facilitator, and inform the parent if appropriate.
EXTERN int	oaa_AddData (ICLTerm *clause, ICLTerm *in_params, ICLTerm **out_params)
	Add a new clause for a DATA solvable (locally and/or remotely).
EXTERN int	oaa_RemoveData (ICLTerm *clause, ICLTerm *in_params, ICLTerm **out_params)
EXTERN int	oaa_ReplaceData (ICLTerm *clause1, ICLTerm *clause2, ICLTerm *in_params, ICLTerm **out_params)
	Change a predicate value to a new one.
EXTERN int	oaa_Id (ICLTerm **my_id)
	Return the Id of the current agent.
EXTERN int	oaa_Name (ICLTerm **my_name)
	Return the name of the current agent.
EXTERN int	oaa_Address (char *connectionId, ICLTerm *Type, ICLTerm **myAddress)
	Returns (one of more) Addresses for this agent.
EXTERN int	oaa_PrimaryAddress (ICLTerm **primaryAddress)
	Returns the primary address for this agent in new memory.
EXTERN int	oaa_PrimaryId (ICLTerm **primaryId)
	Returns the primary id for this agent.
EXTERN int	oaa_Solve (ICLTerm *goal, ICLTerm *initial_params, ICLTerm **out_params, ICLTerm **solutions)
	Sends work or information requests to distributed agents, brokered by the Facilitator agent.
EXTERN int	oaa_InCache (ICLTerm *goal, ICLTerm **solutions)
	Retrieve solutions from the cache if the goal we are asking for is properly contained in the cache (check subsumption).
EXTERN int	oaa_AddToCache (ICLTerm *goal, ICLTerm *solutions)
	Add each solution to goal one at a time so we can retrieve solutions later using findall.
EXTERN int	oaa_ClearCache ()
	Clear the cache.
EXTERN int	oaa_RegisterCallback (char *callback_id, int(*callback_proc)(ICLTerm *, ICLTerm *, ICLTerm *))
	Declare what procedures should be used for callbacks.
EXTERN int	oaa_GetCallback (char *callback_id, int(**callback_proc)(ICLTerm *, ICLTerm *, ICLTerm *))
EXTERN int	oaa_TraceMsg (char *format_string,...)
	If trace mode is on, display message and arguments.
EXTERN char *	oaa_name_string (void)
EXTERN int	memberchk (ICLTerm *Param, ICLTerm *ParamList)
	Searches for a parameter in a list.
EXTERN int	oaa_Connect (char *ConnectionId, ICLTerm *Address, char *InitialAgentName, ICLTerm *Params)
	Connect and handshake with the agent listening on Address, or, if Address is a variable, allow com_Connect() to find the address.
EXTERN int	oaa_Disconnect (char *ConnectionId, ICLTerm *Params)
	Disconnect from the given comm link, or from all links if the given CommunicationID is NULL.
EXTERN int	oaa_SetupCommunication (char *InitialAgentName)
	Convenience function for connecting to a facilitator and, if oaa_listen can be resolved, for opening server listening sockets for to handle direct_connect requests.
EXTERN int	oaa_LibraryVersion (ICLTerm **versionCopy)
EXTERN int	oaa_SupportsSequenceNumbers (char *connectionId)
Variables
EXTERN char const *	oaa_library_version_str

---

Detailed Description

Definition in file liboaa.h.

---

Define Documentation

#define EXTERN   extern

Definition at line 36 of file liboaa.h.

#define FALSE   0

Definition at line 40 of file liboaa.h.

#define OAA_LIBRARY_VERSION   oaa_library_version_str;

Deprecated:

use oaa_LibraryVersion()

Definition at line 154 of file liboaa.h.

#define sleep_millis

(

n

)

usleep((n)*1000L)

Definition at line 164 of file liboaa.h.

#define STREQ	(	str1,
		str2		)	(strcmp((str1), (str2)) == 0)

Definition at line 157 of file liboaa.h.

#define TRUE   1

Definition at line 41 of file liboaa.h.

---

Function Documentation

EXTERN int icl_BasicGoal

(

ICLTerm *

goal

)

Test whether an expression is an ICL basic (non-compound) goal; that is, just a functor with 0 or more arguments.

Remarks:

• Basic goals include built-in's as well as solvables.
• This is a syntactic test; that is, we're not checking whether the Goal is a declared solvable.

Definition at line 1038 of file liboaa.c.

EXTERN int icl_Builtin

(

ICLTerm *

goal

)

EXTERN int icl_ConvertSolvables	(	int	toStandard,
		ICLTerm *	ShorthandSolvables,
		ICLTerm **	StandardSolvables
	)

Convert between shorthand and standard forms of solvables list.

Remarks:

• In the standard form, each element is a term solvable(Goal, Params, Permissions), with Permissions and Params both lists. In the Permissions and Params lists, values appear only when they are OTHER than the default.
• In the shorthand form, each element can be solvable/3, as above, or solvable(Goal, Params), or solvable(Goal), or just Goal.
• Note that "shorthand" means "anything goes" - so shorthand solvables are a superset of standard solvables.
• Permissions (defaults in square brackets): call(T_F) [true], read(T_F) [false], write(T_F) [false]
• Params (defaults in square brackets):
  • type(Data_Procedure) [procedure]
  • callback(Functor) [user:oaa_AppDoEvent]
  • utility(N) [5]
  • synonym(SynonymHead, RealHead) [none]
  • rules_ok(T_F) [false]
  • single_value(T_F) [false]
  • unique_values(T_F) [false]
  • private(T_F) [false]
  • bookkeeping(T_F) [true]
  • persistent(T_F) [false]
• Refer to Agent Library Reference Manual for details on Permissions and Params.

Note: in the C version, an additional arg (toStandard) is added to distinguish between the two calling conventions:

    icl_ConvertSolvables(TRUE, +ShorthandSolvables, -StandardSolvables).

    icl_ConvertSolvables(FALSE, +StandardSolvables, -ShorthandSolvables).
 

Definition at line 1818 of file liboaa.c.

EXTERN int icl_GetParamValue	(	ICLTerm *	Param,
		ICLTerm *	ParamList,
		ICLTerm **	Result
	)

To get or test the value of a parameter that has a default, it is best to call icl_GetParamValue().

For a parameter that has no default, you can use icl_GetParamValue() OR memberchk().

Remarks:

• Param must be a partially- or fully-instantiated structure (atom form will not work)
• Result may be NULL, in which case only a test is performed

Definition at line 1381 of file liboaa.c.

EXTERN int icl_GetPermValue	(	ICLTerm *	Perm,
		ICLTerm *	PermList,
		ICLTerm **	Result
	)

To get or test the value of a parameter that has a default, it is best to call icl_GetPermValue().

For a parameter that has no default, you can use icl_GetPermValue() OR memberchk().

Remarks:

• Perm must be a partially- or fully-instantiated structure (atom form will not work)
• Result may be NULL, in which case only a test is performed

Definition at line 1421 of file liboaa.c.

EXTERN int memberchk	(	ICLTerm *	Param,
		ICLTerm *	ParamList
	)

Searches for a parameter in a list.

Parameters:

	Param	A term to search for
	ParamList	A list to search in

Returns:

TRUE if Param is contained in ParamList

Definition at line 7966 of file liboaa.c.

EXTERN int oaa_AddData	(	ICLTerm *	clause,
		ICLTerm *	in_params,
		ICLTerm **	out_params
	)

Add a new clause for a DATA solvable (locally and/or remotely).

Params:

• address(X): a list including 'self', 'parent', and/or the addresses of other client agents. The default (no address) behavior is the same as with oaa_Solve.
• reflexive(T_F): Save as with oaa_Solve. Default: true.
• at_beginning(T_F): if true, uses asserta instead of assertz. Default: false.
• single_value(T_F): if true, ALL clauses for this predicate are removed before adding the new clause. Default: false.
• unique_values(T_F): if true, at most one copy of each value is stored. Default: false.
• owner(LocalId): if bookkeeping(true) for this solvable, record LocalId as the owner. Default: the agent from which the request originated.
• get_address(X): Returns a list of addresses (ids) of agents that were sent the request.
• get_satisfiers(X): Returns a list of addresses (ids) of agents that successfully completed the request.
• reply({true,none}): When data is being added on a remote agent or agents, this tells whether reply message(s) are desired.
• block(Mode) : true: Block until the reply arrives. : false: Don't block. In this case, the reply events (ev_reply_updated) can be handled by the user's app_do_event callback Default: true. Note that reply(none) overrides block(true).

Remarks:

• Clause is normally a fact (no body), but with Prolog agents, and with rules_ok(true), it's possible for it to have a body.
• Triggers will be examined with the on(add) operation mask

Definition at line 5517 of file liboaa.c.

EXTERN int oaa_AddDelayedContextParams	(	ICLTerm *	id,
		ICLTerm *	params,
		ICLTerm **	new_params
	)

When a goal is delayed using oaa_DelaySolution(), incoming context parameters from the original request can not be automatically concatenated to outgoing oaa_Solve() requests.

Since an agent can manage multiple delayed goals at the same time, liboaa doesn't know the correct context for the outgoing oaa_Solve() without explicit direction from the programmer. Hence, an agent programmer who wants to call oaa_Solve() during a delayed goal is expected to use this function to add the saved contexts for the delayed goal to his/her outgoing oaa_Solve() parameters.

Parameters:

	id	an Id which will be used to later match solutions to request
	params	parameters for solve goal
	new_params	params augmented by saved contexts; points to newly allocated memory--remember to call icl_Free(*new_params)

Definition at line 4318 of file liboaa.c.

EXTERN int oaa_Address	(	char *	connectionId,
		ICLTerm *	Type,
		ICLTerm **	myAddress
	)

Returns (one of more) Addresses for this agent.

If ConnectionId is ground, returns a single Address, relative to that connection. If connection Id is not null, the function returns a single answer for this specific connection. If the connection bound to the incoming Id is not valid, (not actually connected), returns "no_address" and prints out a warning. If connection Id is null, returns all the addresses of the currently valid connections.

Definition at line 6274 of file liboaa.c.

EXTERN int oaa_AddToCache	(	ICLTerm *	goal,
		ICLTerm *	solutions
	)

Add each solution to goal one at a time so we can retrieve solutions later using findall.

Definition at line 7091 of file liboaa.c.

EXTERN int oaa_CanSolve	(	ICLTerm *	goal,
		ICLTerm **	kslist
	)

Asks the Facilitator for a list of agents which could solve a Goal.

Definition at line 4657 of file liboaa.c.

EXTERN int oaa_ClearCache

(

)

Clear the cache.

Definition at line 7108 of file liboaa.c.

EXTERN int oaa_Connect	(	char *	ConnectionId,
		ICLTerm *	Address,
		char *	InitialAgentName,
		ICLTerm *	Params
	)

Connect and handshake with the agent listening on Address, or, if Address is a variable, allow com_Connect() to find the address.

See also:

com_Connect()

Definition at line 8009 of file liboaa.c.

EXTERN int oaa_Declare	(	ICLTerm *	solvable,
		ICLTerm *	initial_common_perms,
		ICLTerm *	initial_common_params,
		ICLTerm *	initial_params,
		ICLTerm **	declared_solvables
	)

Declare solvables for a client or facilitator, and inform the parent if appropriate.

Parameters:

	solvable	a single solvable or a list of solvables, in shorthand or standard form
	initial_common_perms	permissions to be distributed to each solvable in solvable. This is purely for programming convenience. See comments for icl_ConvertSolvables() for possible values, and solvables documentation for their meanings.
	initial_common_params	params to be distributed to each solvable in Solvables. This is purely for programming convenience. See comments for icl_ConvertSolvables() for possible values, and solvables documentation for their meanings.
	declared_solvables	returns a list, in standard form, of all solvables successfully declared.

Params:

• address(X): Where the solvable will exist. X may be either 'self' or 'parent' (or the appropriate local ids). Default: 'self'.
• if_exists(OverwriteOrAppend): What to do when declaring solvables for self, and some already exist. Default: append.

Remarks

• Any agent can declare solvables for itself. In addition, a client can ask its facilitator to declare solvables. Client-requested facilitato solvables will automatically acquire permission write(true), and params type(data), rules_ok(false), private(false), and bookkeeping(true).
• If called by a leaf or node agent, assumes agent is already registered with a parent facilitator.
• Predicates can only be declared once. Changing an existing predicate definition should be done with oaa_Redeclare. However, a request to declare a predicate, which is already declared in precisely the same way, succeeds transparently.
• synonym predicates can have their own triggers, but share the clause database with their master table.
• views and filters, as provided by the OAA V1 DB agent, are not supported as separate params, but the same functionality is available using other params.

Definition at line 4765 of file liboaa.c.

EXTERN int oaa_DeclareData	(	ICLTerm *	solv,
		ICLTerm *	params,
		ICLTerm **	declared_solvs
	)

Declare data solvables for an agent.

Definition at line 4823 of file liboaa.c.

EXTERN int oaa_DelaySolution

(

ICLTerm *

id

)

Requests that the current AppDoEvent not return solutions to the current goal until a later time.

Parameters:

id

an Id which will be used to later match solutions to request

Definition at line 4203 of file liboaa.c.

EXTERN int oaa_Disconnect	(	char *	ConnectionId,
		ICLTerm *	Params
	)

Disconnect from the given comm link, or from all links if the given CommunicationID is NULL.

Parameters:

	ConnectionId	the link to disconnect; if NULL, disconnect from all links
	Params	for future enhancements; currently ignored.

Returns:

TRUE if successful, FALSE otherwise.

Definition at line 8243 of file liboaa.c.

EXTERN int oaa_GetCallback	(	char *	callback_id,
		int(**)(ICLTerm *, ICLTerm *, ICLTerm *)	callback_proc
	)

Definition at line 7352 of file liboaa.c.

EXTERN void oaa_GetEvent	(	ICLTerm **	Event,
		ICLTerm **	Params,
		int	LowestPriority
	)

Return the next event to execute.

Remarks:

• If a oaa_timeout(Secs) is set to a positive real number by oaa_SetTimeout(), wait Secs for an event. If none arrives in this time, return Event = `timeout'
• Reads ALL events available on communication stream, sorts the events according to priority, chooses the next event to execute, and then saves the rest for next time oaa_GetEvent is called.
• The communication stream is read every time oaa_GetEvent is called, even if there are already saved events (a new one might have a higher priority!)
• If saved events exist, return immediately (timeout not considered).

Definition at line 2686 of file liboaa.c.

int oaa_Id

(

ICLTerm **

my_id

)

Return the Id of the current agent.

Definition at line 6231 of file liboaa.c.

EXTERN int oaa_InCache	(	ICLTerm *	goal,
		ICLTerm **	solutions
	)

Retrieve solutions from the cache if the goal we are asking for is properly contained in the cache (check subsumption).

Definition at line 7081 of file liboaa.c.

EXTERN int oaa_Init	(	int	argc,
		char *	argv[]
	)

Must be called to init oaa parameters, such as argv and agrc.

In the multithreaded version, starts the oaa thread.

Definition at line 164 of file liboaa.c.

EXTERN int oaa_Interpret	(	ICLTerm *	goal,
		ICLTerm *	params,
		ICLTerm **	solutions
	)

Executes an incoming event Implements a simple meta-interpreter for executing complex goals.

Agent goals are interpreted by oaa_exec_event(). The contents of Params will vary depending on context. When oaa_Interpret is called on an incoming event, Params will (usually) include from(Sender). Calls generated internally may contain from(self). Additional params may accumulate through recursive calls to oaa_Interpret.

Definition at line 3620 of file liboaa.c.

EXTERN int oaa_LibraryVersion

(

ICLTerm **

versionCopy

)

Definition at line 4580 of file liboaa.c.

EXTERN void oaa_MainLoop

(

int

ShouldPrint

)

The main event loop for the application.

Reads an event, executes (interprets) it, checks on_receive triggers for the event, checks any application-dependent triggers.

Definition at line 2493 of file liboaa.c.

EXTERN int oaa_Name

(

ICLTerm **

my_name

)

Return the name of the current agent.

Definition at line 6390 of file liboaa.c.

char * oaa_name_string

(

void

)

Definition at line 6422 of file liboaa.c.

EXTERN int oaa_Ping	(	ICLTerm *	agent_addr,
		double	time_limit,
		double *	total_response_time
	)

Tests whether a given agent is currently responding to requests.

Fails if a ping is not returned in TimeLimit amount of time.

Parameters:

	AgentAddr	the address of agent to test
	TimeLimit	the time limit (in seconds) for how long to wait for a response
	TotalResponseTime	the time for the round trip (in seconds)

Definition at line 4679 of file liboaa.c.

EXTERN int oaa_PostEvent	(	ICLTerm *	contents,
		ICLTerm *	params
	)

Sends a low-level event to another agent.

Should NOT be used before there's a connection established for the destination (such as when a client sends ev_connect to its facilitator). In such unusual cases, use com_SendData() directly. For application developers, this just means don't call oaa_PostEvent() until after you've called oaa_Register().

Parameters may include:

• priority(P):
• address(A): specify address of specific server or client agent A must be an agent ID, not a name. If caller is a client agent, the only meaningful address is that of the client's facilitator.
• from(KS): where the event originally originated

IMPORTANT: there may be a different address INSIDE the event; these should not be confused!

Definition at line 4381 of file liboaa.c.

EXTERN int oaa_PrimaryAddress

(

ICLTerm **

primaryAddress

)

Returns the primary address for this agent in new memory.

Definition at line 6339 of file liboaa.c.

EXTERN int oaa_PrimaryId

(

ICLTerm **

primaryId

)

Returns the primary id for this agent.

Definition at line 6360 of file liboaa.c.

EXTERN void oaa_ProcessAllEvents

(

)

To be called when the application that uses OAA has its own event loop.

Reads an event, executes (interprets) it, checks on_receive triggers for the event, checks any application-dependent triggers.

Definition at line 2518 of file liboaa.c.

EXTERN void oaa_ProcessEvent	(	ICLTerm *	Event,
		ICLTerm *	Params
	)

Interprets an incoming event.

For a timeout, checks task triggers and calls user's idle procedure Otherwise, oaa_Interprets the event, checks on_receive comm triggers, and then checks task triggers.

Definition at line 2615 of file liboaa.c.

EXTERN void oaa_Ready

(

int

ShouldPrint

)

Changes the agent's 'open' status to 'ready', indicating that the agent is now ready to receive message.

If requested, prints 'Ready' to standard out.

Definition at line 941 of file liboaa.c.

EXTERN int oaa_Redeclare	(	ICLTerm *	initial_solvable,
		ICLTerm *	initial_new_solvable,
		ICLTerm *	initial_params
	)

Replace a solvable on a client or facilitator, and inform the parent if appropriate.

Parameters:

	initial_solvable	a single solvable, in shorthand or standard form. If in standard form, however, ONLY the goal is considered in selecting the solvable to be replaced (permissions and parameters are ignored).
	initial_new_solvable	a single solvable, in shorthand or standard form.

Params:

• address(X): Where the solvable exists. X may be either 'self' or 'parent' (or the appropriate local ids). Default: 'self'.

Remarks:

• If called by a leaf or node agent, assumes agent is already registered with a parent facilitator.
• FAILS if the operation cannot be completed.

Definition at line 4892 of file liboaa.c.

EXTERN int oaa_Register	(	char *	ConnectionId,
		char *	AgentName,
		ICLTerm *	Solvables
	)

Once a comm link is established, either as a client to a Facilitator or as a server for other agents, oaa_Register will setup and registration information for this agent.

The following information is stored about the current connection, accessible through com_GetInfo(ConnectionId, Info):

• oaa_name(Name) : the name of the current agent
• oaa_id(Id) : the Id for the agent
• connection(C) : system-level communications handle (e.g., socket number)

if connecting as client, this is also available:

• fac_id(Id) : the Facilitator's Id
• fac_name(Name) : the Facilitator's name
• fac_lang(L) : the Facilitator's language
• fac_version(V) : the version of the Facilitator's agent library

In addition, the following predicates are written to parent Facilitator, or locally if the ConnectionId is a server connection:

• agent_host(Id, Name, Host)

Solvables are also written using oaa_Declare().

Parameters:

	ConnectionId	the symbolic connection Id (client or server connection)
	AgentName	the name of the agent
	Solvables	solvable list

Definition at line 824 of file liboaa.c.

EXTERN int oaa_RegisterCallback	(	char *	callback_id,
		int(*)(ICLTerm *, ICLTerm *, ICLTerm *)	callback_proc
	)

Declare what procedures should be used for callbacks.

These are application-defined procedures called by library code.

Definition at line 7325 of file liboaa.c.

EXTERN int oaa_RemoveData	(	ICLTerm *	clause,
		ICLTerm *	in_params,
		ICLTerm **	out_params
	)

Definition at line 5555 of file liboaa.c.

EXTERN int oaa_ReplaceData	(	ICLTerm *	clause1,
		ICLTerm *	clause2,
		ICLTerm *	in_params,
		ICLTerm **	out_params
	)

Change a predicate value to a new one.

Parameters:

	clause1	must be a clause of a writable data solvable.
	clause2	must be a clause of a writable data solvable.

Params:

• address(X): a list including 'self', 'parent', and/or the addresses of other client agents. The default (no address) behavior is the same as with oaa_Solve and oaa_AddData.
• reflexive(T_F): Save as with oaa_Solve. Default: true.
• do_all(T_F): If, true, changes all predicate values that match the clause1 specification default is 'false': changes only the first
• at_beginning(T_F): If true, uses asserta instead of assertz default is 'false'
• owner(LocalId): if bookkeeping(true) for this solvable, record LocalId as the owner of each new data item. Note: It is not possible to specify the owner of the data to be replaced, just that of the NEW data. Default: the agent from which the request originated.
• get_address(X): Returns a list of addresses (ids) of agents that were sent the request.
• get_satisfiers(X): Returns a list of addresses (ids) of agents that successfully completed the request.
• reply({true,none}): When data is being replaced on a remote agent or agents, this tells whether reply message(s) are desired.
• block(Mode): true: Block until the reply arrives. : false: Don't block. In this case, the reply events (ev_reply_updated) can be handled by the user's app_do_event callback Default: true. Note that reply(none) overrides block(true).

Remarks:

• clause1 and/or clause2 may be synonym predicates.
• clause1 and clause2 are not required to have the same functor.
• clause1 and clause2 may share variables.
• Triggers will be examined with the 'remove' operation mask with clause1, and the 'add' operation mask with clause2.
• db_replace triggers on the Pred2 argument, not on the Pred1 arg
• at_beginning param only used if do_all is false

Definition at line 5602 of file liboaa.c.

EXTERN int oaa_ReturnDelayedSolutions	(	ICLTerm *	id,
		ICLTerm *	solution_list
	)

Returns the list of solutions for a delayed request.

Parameters:

id

an Id referring to a previously saved oaa_DelaySolution

Definition at line 4219 of file liboaa.c.

EXTERN void oaa_SetTimeout

(

double

NSecs

)

Sets the timeout value used by oaa_GetEvent().

Definition at line 2658 of file liboaa.c.

EXTERN int oaa_SetupCommunication

(

char *

InitialAgentName

)

Convenience function for connecting to a facilitator and, if oaa_listen can be resolved, for opening server listening sockets for to handle direct_connect requests.

Definition at line 8484 of file liboaa.c.

EXTERN int oaa_Solve	(	ICLTerm *	goal,
		ICLTerm *	initial_params,
		ICLTerm **	out_params,
		ICLTerm **	solutions
	)

Sends work or information requests to distributed agents, brokered by the Facilitator agent.

The default behavior (paramlist = []) is to act like the Prolog primitive call(Goal), blocking until Goal is finished, and unifying and backtracking over solutions for Goal.

This behavior may be modified by a parameter list, which may contain:

• cache(T_F): cache all solutions locally, and if good solutions already exist in the cache, use the local values instead of making a distributed request. Default: false.

• level_limit(N): highest number of hierarchical levels to climb for solutions.

• address(AgentId): send request to specific agent, given its name or Addr If AgentID is 'self', solves the goal locally.

• reply(Mode): true: Reply desired. : none: No reply desired. Default: true, except when the call to oaa_Solve is a trigger action, in which case it is none. 'none' is used here instead of false, because we anticipate some additional values.

• block(Mode): true: Block until the reply arrives. : false: Don't block. In this case, the reply events (ev_reply_solved) can be handled by the user's app_do_event callback Default: true, except when the call to oaa_Solve is a trigger action, in which case it is false. Note that reply(none) overrides block(true).

• solution_limit(N): limits the maximum number of solutions found to N

• time_limit(N): Waits a maximum of N seconds before returning (failure if no solution found in time).

• context(C): Passes a context value through any subsequent solves.

• parallel_ok(T_F): if T_F is 'true' (default), multiple agents that can solve the Goal will attempt to work on it in parallel. If 'false', one agent will be selected at a time to solve the goal, until the maximum number of requested solutions (see solution_limit) is found.

• reflexive(T_F): If T_F is `true', the Facilitator will consider the originating agent when choosing agents to solve a request. Default: true.

• priority(P): P ranges from 1 (low priority) to 10 (high priority) with a default of 5.

• flush_events(T_F): Will flush (dispose of) all events of lower priority currently queued at the destination agent. These events are lost, and will not be executed. This parameter should be used with caution!!! Default: false.

• direct_connect(T_F): If true, a direct peer-peer connection will be attempted with the client.

• get_address(X): Returns a list of addresses (ids) of agents that were asked to solve the goal, or one of its subgoals.

• get_satisfiers(X): Returns a list of addresses (ids) of agents that succeeded in solving the goal, or one of its subgoals.

• get_direct_connect_used(X): Returns "true" or "false" indicating if direct_connect was actually used.

• strategy(S): Shorthand for certain combinations of the above parameters. S is one of query = [parallel_ok(true)] action = [parallel_ok(false), solution_limit(1)] inform = [parallel_ok(true), reply(none)]

Note that certain combinations of parameters are inconsistent, and are handled as follows:

• reply(none) overrides block(true)
• reply(none) overrides parallel_ok(false)

All of the above parameters may be used in the "global" parameter list (the second argument to oaa_Solve), when Goal is non-compound. Most can be used in the global list with compound goals also. Some of these parameters can also be used in the NESTED parameter lists of compound goals. Uses of these parameters with compound goals are documented elsewhere. When that documentation exists, this will go there: With many compound goals, however, the get_satisfier/1 parameter isn't really meaningful. Thus, with compound goals, it is often best to use this parameter in a nested parameter list.

Definition at line 6706 of file liboaa.c.

EXTERN int oaa_SupportsSequenceNumbers

(

char *

connectionId

)

Definition at line 8584 of file liboaa.c.

EXTERN int oaa_TraceMsg	(	char *	format_string,
			...
	)

If trace mode is on, display message and arguments.

Definition at line 7436 of file liboaa.c.

EXTERN int oaa_Undeclare	(	ICLTerm *	solvable,
		ICLTerm *	initial_params,
		ICLTerm **	undeclared_solvables
	)

Remove solvables from a client or facilitator, and inform the parent if appropriate.

If called by a leaf or node agent, assumes agent it is already registered with a parent facilitator.

Parameters:

	solvable	a single solvable or a list of solvables, in shorthand or standard form. If a solvable is in standard form, however, ONLY the goal is considered in selecting the solvables to be removed (permissions and parameters are ignored).
	initial_params	address(X): Where the solvable exists. X may be either 'self' or 'parent' (or the appropriate local ids). Default: 'self'.
	undeclared_solvables	returns a list, in standard form, of all solvables successfully removed.

Definition at line 4856 of file liboaa.c.

EXTERN int oaa_ValidateEvent	(	ICLTerm *	E,
		ICLTerm **	OkEvent
	)

Check that an incoming lowlevel event should be processed.

This is the place to put security checks on events. The default behavior defined by the library can be made more stringent by individual agents using the callback oaa_AppValidateEvent(). oaa_ValidateEvent() has the right to modify the incoming event, or refuse it altogether by failing. This will return a newly allocated ICLTerm.

Definition at line 3005 of file liboaa.c.

EXTERN int oaa_Version	(	ICLTerm *	agent_id,
		ICLTerm **	language,
		ICLTerm **	version
	)

Lookup the language and library version number for an agent.

The default version (if unspecified) is 1.0.

Definition at line 4593 of file liboaa.c.

---

Variable Documentation

EXTERN char const* oaa_library_version_str

Deprecated:

use oaa_LibraryVersion()

Definition at line 145 of file liboaa.h.

---