/home/dko/projects/mobilec/trunk/src/include/libmc.h File Reference

MobileC api header file. More...

#include <embedch.h>

Go to the source code of this file.

Data Structures

struct agency_s

The agency handle. More...

struct MCAgencyOptions_s

User modifiable agency options. More...

Defines

#define EXPORTMC

#define MC_Wait(arg1) MC_MainLoop(arg1)

Typedefs

typedef enum error_code_e error_code_t

typedef enum MC_SteerCommand_e MC_SteerCommand_t

typedef struct agency_s agency_t

typedef agency_t * agency_p

typedef agency_p MCAgency_t

typedef struct MCAgencyOptions_s MCAgencyOptions_t

typedef struct agent_s agent_t

typedef agent_t * MCAgent_t

typedef agent_t * agent_p

Enumerations

enum MC_ThreadIndex_e {
MC_THREAD_DF = 0, MC_THREAD_AMS, MC_THREAD_ACC, MC_THREAD_CP,
MC_THREAD_AGENT, MC_THREAD_ALL
}

MobileC Module indices. More...

enum MC_SteerCommand_e { MC_RUN = 0, MC_SUSPEND, MC_RESTART, MC_STOP }

Available commands for MC_Steer. More...

enum MC_Signal_e {
MC_NO_SIGNAL = 0x00, MC_RECV_CONNECTION = 0x01, MC_RECV_MESSAGE = 0x02, MC_RECV_AGENT = 0x04,
MC_RECV_RETURN = 0x08, MC_EXEC_AGENT = 0x10, MC_ALL_SIGNALS = 0x20
}

MobileC system signals. More...

enum MC_AgentType_e { MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT }

enum MC_AgentStatus_e {
MC_NO_STATUS = -1, MC_WAIT_CH = 0, MC_WAIT_MESSGSEND, MC_AGENT_ACTIVE,
MC_AGENT_NEUTRAL, MC_AGENT_SUSPENDED, MC_WAIT_FINISHED
}

An agent's current execution state. More...

enum fipa_performative_e {
FIPA_ERROR = -1, FIPA_ZERO, FIPA_ACCEPT_PROPOSAL, FIPA_AGREE,
FIPA_CANCEL, FIPA_CALL_FOR_PROPOSAL, FIPA_CONFIRM, FIPA_DISCONFIRM,
FIPA_FAILURE, FIPA_INFORM, FIPA_INFORM_IF, FIPA_INFORM_REF,
FIPA_NOT_UNDERSTOOD, FIPA_PROPOGATE, FIPA_PROPOSE, FIPA_PROXY,
FIPA_QUERY_IF, FIPA_QUERY_REF, FIPA_REFUSE, FIPA_REJECT_PROPOSAL,
FIPA_REQUEST, FIPA_REQUEST_WHEN, FIPA_REQUEST_WHENEVER, FIPA_SUBSCRIBE,
FIPA_ERROR = -1, FIPA_ZERO, FIPA_ACCEPT_PROPOSAL, FIPA_AGREE,
FIPA_CANCEL, FIPA_CALL_FOR_PROPOSAL, FIPA_CONFIRM, FIPA_DISCONFIRM,
FIPA_FAILURE, FIPA_INFORM, FIPA_INFORM_IF, FIPA_INFORM_REF,
FIPA_NOT_UNDERSTOOD, FIPA_PROPOGATE, FIPA_PROPOSE, FIPA_PROXY,
FIPA_QUERY_IF, FIPA_QUERY_REF, FIPA_REFUSE, FIPA_REJECT_PROPOSAL,
FIPA_REQUEST, FIPA_REQUEST_WHEN, FIPA_REQUEST_WHENEVER, FIPA_SUBSCRIBE
}

Functions

EXPORTMC int MC_AclDestroy (struct fipa_acl_message_s *message)

Destroy a FIPA ACL message.

EXPORTMC struct
fipa_acl_message_s * MC_AclNew (void)

Allocate a new ACL Message.

EXPORTMC int MC_AclPost (MCAgent_t agent, struct fipa_acl_message_s *message)

Post ACL message to agent.

EXPORTMC struct
fipa_acl_message_s * MC_AclReply (struct fipa_acl_message_s *acl_message)

Reply to an ACL message.

EXPORTMC struct
fipa_acl_message_s * MC_AclRetrieve (MCAgent_t agent)

Retrieve an ACL message.

EXPORTMC int MC_AclSend (MCAgency_t attr, struct fipa_acl_message_s *acl)

Send a composed ACL Message.

EXPORTMC struct
fipa_acl_message_s * MC_AclWaitRetrieve (MCAgent_t agent)

Wait for and retrieve an ACL message.

EXPORTMC int MC_AclSetPerformative (struct fipa_acl_message_s *acl, enum fipa_performative_e performative)

EXPORTMC int MC_AclSetSender (struct fipa_acl_message_s *acl, const char *name, const char *address)

EXPORTMC int MC_AclAddReceiver (struct fipa_acl_message_s *acl, const char *name, const char *address)

EXPORTMC int MC_AclAddReplyTo (struct fipa_acl_message_s *acl, const char *name, const char *address)

EXPORTMC int MC_AclSetContent (struct fipa_acl_message_s *acl, const char *content)

EXPORTMC int MC_AddAgent (MCAgency_t attr, MCAgent_t agent)

Add an agent to the agency 'attr'.

const void * MC_AgentVariableRetrieve (MCAgent_t agent, const char *var_name, int task_num)

Retrieve a pointer to a previously saved variable.

int MC_AgentVariableSave (MCAgent_t agent, const char *var_name)

Mark an agent variable for saving.

EXPORTMC int MC_BarrierDelete (MCAgency_t attr, int id)

Find and delete an initialized MobileC Barrier.

EXPORTMC int MC_BarrierInit (MCAgency_t attr, int id, int num_procs)

Initialize a MobileC Barrier.

EXPORTMC int MC_ChInitializeOptions (MCAgency_t attr, ChOptions_t *options)

Use custom ChOptions_t type for internal Ch interpretor.

EXPORTMC int MC_CallAgentFunc (MCAgent_t agent, const char *funcName, void *returnVal, int numArgs,...)

Calls a function defined in an agent.

EXPORTMC int MC_CallAgentFuncArg (MCAgent_t agent, const char *funcName, void *returnVal, void *arg)

Calls a function defined in an agent.

EXPORTMC int MC_CallAgentFuncV (MCAgent_t agent, const char *funcName, void *returnVal, va_list ap)

Calls a function defined in an agent.

EXPORTMC int MC_CallAgentFuncVar (MCAgent_t agent, const char *funcName, void *returnVal, ChVaList_t arglist)

MCAgent_t MC_ComposeAgent (const char *name, const char *home, const char *owner, const char *code, const char *return_var_name, const char *server, int persistent)

Compose a new agent dynamically without using a prewritten XML file.

EXPORTMC int MC_CondBroadcast (MCAgency_t attr, int id)

Wakes up all agents/threads waiting on a condition variable.

EXPORTMC int MC_CondSignal (MCAgency_t attr, int id)

Wakes up at least one thread waiting on a condition variable.

EXPORTMC int MC_CondReset (MCAgency_t attr, int id)

Reset a previously signalled MobileC condition variable.

EXPORTMC int MC_CondWait (MCAgency_t attr, int id)

Wait on a MobileC synchronization variable.

int MC_CopyAgent (MCAgent_t *agent_out, const MCAgent_t agent_in)

Performs a deep-copy of an agent structure.

EXPORTMC int MC_DeleteAgent (MCAgent_t agent)

Stop and remove an agent.

EXPORTMC int MC_End (MCAgency_t attr)

End an agency.

int MC_DestroyServiceSearchResult (char **agentName, char **serviceName, int *agentID, int numResult)

Free memory allocated by a Service Search operation.

EXPORTMC MCAgent_t MC_FindAgentByName (MCAgency_t attr, const char *name)

Find an agent by its name.

EXPORTMC MCAgent_t MC_FindAgentByID (MCAgency_t attr, int ID)

Find an agent by its id.

EXPORTMC void * MC_GetAgentExecEngine (MCAgent_t agent)

Retrieve an agent's Ch interpreter.

EXPORTMC int MC_GetAgentID (MCAgent_t agent)

Retrieve an agent's id.

EXPORTMC char * MC_GetAgentName (MCAgent_t agent)

EXPORTMC int MC_GetAgentNumTasks (MCAgent_t agent)

Retrive the number of tasks an agent has.

EXPORTMC int MC_GetAgentReturnData (MCAgent_t agent, int task_num, void **data, int *dim, int **extent)

Get an agent's return data.

EXPORTMC int MC_GetAgentStatus (MCAgent_t agent)

Get an agent's current status.

EXPORTMC enum MC_AgentType_e MC_GetAgentType (MCAgent_t agent)

Get an agent's type.

EXPORTMC char * MC_GetAgentXMLString (MCAgent_t agent)

Get an agent's xml string.

EXPORTMC int MC_HaltAgency (MCAgency_t agency)

Halt an agency: Do not process new entries in queues.

EXPORTMC MCAgency_t MC_Initialize (int port, MCAgencyOptions_t *options)

Initialize and start a MobileC agency.

EXPORTMC int MC_InitializeAgencyOptions (struct MCAgencyOptions_s *options)

Initialize MobileC options.

EXPORTMC int MC_MainLoop (MCAgency_t attr)

Wait indefinitely.

EXPORTMC int MC_LoadAgentFromFile (MCAgency_t attr, const char *filename)

Load an agent from a file into an agency.

EXPORTMC int MC_MutexLock (MCAgency_t attr, int id)

Locks a MobileC synchronization variable as a mutex.

EXPORTMC int MC_MutexUnlock (MCAgency_t attr, int id)

EXPORTMC int MC_RegisterService (MCAgency_t agency, MCAgent_t agent, int agentID, const char *agentName, char **serviceNames, int numServices)

EXPORTMC int MC_ResumeAgency (MCAgency_t agency)

Resumes a halted agency.

EXPORTMC MCAgent_t MC_RetrieveAgent (MCAgency_t attr)

Retrieves the oldest agent from an agency.

EXPORTMC int MC_SemaphorePost (MCAgency_t attr, int id)

Post to a MobileC synchronization variable semaphore.

EXPORTMC int MC_SemaphoreWait (MCAgency_t attr, int id)

Decreases a MobileC synchronization variable semaphore count by one.

EXPORTMC int MC_SetDefaultAgentStatus (MCAgency_t agency, enum MC_AgentStatus_e status)

Sets default incoming agent status.

EXPORTMC int MC_SetThreadOn (MCAgencyOptions_t *options, enum MC_ThreadIndex_e index)

Sets a MobileC thread to "on" status.

EXPORTMC int MC_SetThreadsAllOn (MCAgencyOptions_t *options)

Set all Mobile-C threads on.

EXPORTMC int MC_SetThreadOff (MCAgencyOptions_t *options, enum MC_ThreadIndex_e index)

Sets a MobileC thread to "off" status.

EXPORTMC int MC_SetThreadsAllOff (MCAgencyOptions_t *options)

Set all MobileC threads to 'off' status.

EXPORTMC int MC_PrintAgentCode (MCAgent_t agent)

Prints an agents code to stdout.

EXPORTMC char * MC_RetrieveAgentCode (MCAgent_t agent)

Retrieves an agent's Ch code.

EXPORTMC int MC_ResetSignal (MCAgency_t attr)

Reset a MobileC signal.

EXPORTMC int MC_SearchForService (MCAgency_t attr, const char *searchString, char ***agentNames, char ***serviceNames, int **agentIDs, int *numResults)

Search the directory facilitator for a service.

EXPORTMC int MC_SendAgentMigrationMessage (MCAgency_t attr, const char *message, const char *hostname, int port)

Sends an agent migration message.

EXPORTMC int MC_SendAgentMigrationMessageFile (MCAgency_t attr, const char *filename, const char *hostname, int port)

Sends an agent migration message.

EXPORTMC int MC_SetAgentStatus (MCAgent_t agent, int status)

Set an agent's status.

EXPORTMC int MC_Steer (MCAgency_t attr, int(*funcptr)(void *data), void *arg)

Set up a steerable algorithm.

EXPORTMC enum MC_SteerCommand_e MC_SteerControl (void)

The MobileC user-algorithm steering function.

EXPORTMC int MC_SyncDelete (MCAgency_t attr, int id)

Deletes a previously initialized synchronization variable.

EXPORTMC int MC_SyncInit (MCAgency_t attr, int id)

Initializes a new MobileC synchronization variable.

EXPORTMC int MC_TerminateAgent (MCAgent_t agent)

Halt a running agent.

EXPORTMC int MC_WaitAgent (MCAgency_t attr)

Wait indefinitely.

EXPORTMC MCAgent_t MC_WaitRetrieveAgent (MCAgency_t attr)

Wait and retrieve an agent.

EXPORTMC int MC_WaitSignal (MCAgency_t attr, int signals)

Wait for a MobileC signal.

Detailed Description

MobileC api header file.

Definition in file libmc.h.

Define Documentation

#define EXPORTMC

Definition at line 138 of file libmc.h.

#define MC_Wait ( arg1 ) MC_MainLoop(arg1)

Definition at line 143 of file libmc.h.

Typedef Documentation

typedef agency_t* agency_p

Definition at line 229 of file libmc.h.

typedef struct agency_s agency_t

typedef agent_t* agent_p

Definition at line 249 of file libmc.h.

typedef struct agent_s agent_t

Definition at line 247 of file libmc.h.

typedef enum error_code_e error_code_t

typedef enum MC_SteerCommand_e MC_SteerCommand_t

typedef agency_p MCAgency_t

Definition at line 230 of file libmc.h.

typedef struct MCAgencyOptions_s MCAgencyOptions_t

typedef agent_t* MCAgent_t

Definition at line 248 of file libmc.h.

Enumeration Type Documentation

enum error_code_e

Enumerator:: MC_SUCCESS

MC_ERR

MC_ERR_CONNECT

MC_ERR_PARSE

MC_ERR_EMPTY

MC_ERR_INVALID

MC_ERR_INVALID_ARGS

MC_ERR_NOT_FOUND

MC_ERR_MEMORY

MC_ERR_SEND

MC_WARN_DUPLICATE

MC_SUCCESS

ERR

MC_ERR_CONNECT

MC_ERR_PARSE

MC_ERR_EMPTY

MC_ERR_INVALID

MC_ERR_INVALID_ARGS

MC_ERR_NOT_FOUND

MC_ERR_MEMORY

MC_ERR_SEND

MC_WARN_DUPLICATE

Definition at line 157 of file libmc.h.

enum fipa_performative_e

Enumerator:: FIPA_ERROR

FIPA_ZERO

FIPA_ACCEPT_PROPOSAL

FIPA_AGREE

FIPA_CANCEL

FIPA_CALL_FOR_PROPOSAL

FIPA_CONFIRM

FIPA_DISCONFIRM

FIPA_FAILURE

FIPA_INFORM

FIPA_INFORM_IF

FIPA_INFORM_REF

FIPA_NOT_UNDERSTOOD

FIPA_PROPOGATE

FIPA_PROPOSE

FIPA_PROXY

FIPA_QUERY_IF

FIPA_QUERY_REF

FIPA_REFUSE

FIPA_REJECT_PROPOSAL

FIPA_REQUEST

FIPA_REQUEST_WHEN

FIPA_REQUEST_WHENEVER

FIPA_SUBSCRIBE

FIPA_ERROR

FIPA_ZERO

FIPA_ACCEPT_PROPOSAL

FIPA_AGREE

FIPA_CANCEL

FIPA_CALL_FOR_PROPOSAL

FIPA_CONFIRM

FIPA_DISCONFIRM

FIPA_FAILURE

FIPA_INFORM

FIPA_INFORM_IF

FIPA_INFORM_REF

FIPA_NOT_UNDERSTOOD

FIPA_PROPOGATE

FIPA_PROPOSE

FIPA_PROXY

FIPA_QUERY_IF

FIPA_QUERY_REF

FIPA_REFUSE

FIPA_REJECT_PROPOSAL

FIPA_REQUEST

FIPA_REQUEST_WHEN

FIPA_REQUEST_WHENEVER

FIPA_SUBSCRIBE

Definition at line 271 of file libmc.h.

enum MC_AgentStatus_e

An agent's current execution state.

Enumerator:: MC_NO_STATUS

MC_WAIT_CH Waiting to be started

MC_WAIT_MESSGSEND Finished, waiting to migrate

MC_AGENT_ACTIVE Running

MC_AGENT_NEUTRAL Not running, but do not flush

MC_AGENT_SUSPENDED Unused

MC_WAIT_FINISHED Finished, waiting to be flushed

Definition at line 257 of file libmc.h.

enum MC_AgentType_e

Enumerator:: MC_NONE

MC_REMOTE_AGENT

MC_LOCAL_AGENT

MC_RETURN_AGENT

Definition at line 252 of file libmc.h.

enum MC_Signal_e

MobileC system signals.

Note:: Each signal is activated after the corresponding action. i.e. The 'MC_RECV_MESSAGE' signal is activated after a message is received.

See also:: MC_WaitSignal(), MC_ResetSignal

Enumerator:: MC_NO_SIGNAL No signal hass been received

MC_RECV_CONNECTION A Connection has been received

MC_RECV_MESSAGE A Message has been received from a connection

MC_RECV_AGENT An normal agent has been parsed from a message

MC_RECV_RETURN A return agent has been parsed from a message

MC_EXEC_AGENT A normal agent has been executed.

MC_ALL_SIGNALS Catch any of the above signals

Definition at line 202 of file libmc.h.

enum MC_SteerCommand_e

Available commands for MC_Steer.

Enumerator:: MC_RUN Continue the algorithm

MC_SUSPEND Suspend/pause the algorithm

MC_RESTART Restart the algorithm from the beginning

MC_STOP Stop the algorithm

Definition at line 187 of file libmc.h.

enum MC_ThreadIndex_e

MobileC Module indices.

Enumerator:: MC_THREAD_DF Directory Facilitator

MC_THREAD_AMS Agent Managment system

MC_THREAD_ACC Agency communications

MC_THREAD_CP Command Prompt

MC_THREAD_AGENT Agent threads

MC_THREAD_ALL

Definition at line 175 of file libmc.h.

Function Documentation

EXPORTMC int MC_AclAddReceiver ( struct fipa_acl_message_s * acl,

const char * name,

const char * address

)

Definition at line 229 of file libmc.c.

References fipa_agent_identifier_s::addresses, fipa_agent_identifier_New(), fipa_agent_identifier_set_New(), fipa_agent_identifier_set_s::fipa_agent_identifiers, fipa_url_New(), fipa_url_sequence_New(), fipa_agent_identifier_s::name, fipa_url_sequence_s::num, fipa_agent_identifier_set_s::num, fipa_acl_message_s::receiver, fipa_acl_message_s::receiver_num, fipa_url_s::str, and fipa_url_sequence_s::urls.

Referenced by MC_AclAddReceiver_chdl().

EXPORTMC int MC_AclAddReplyTo ( struct fipa_acl_message_s * acl,

const char * name,

const char * address

)

Definition at line 265 of file libmc.c.

References fipa_agent_identifier_s::addresses, fipa_agent_identifier_New(), fipa_agent_identifier_set_New(), fipa_agent_identifier_set_s::fipa_agent_identifiers, fipa_url_New(), fipa_url_sequence_New(), fipa_agent_identifier_s::name, fipa_url_sequence_s::num, fipa_agent_identifier_set_s::num, fipa_acl_message_s::reply_to, fipa_url_s::str, and fipa_url_sequence_s::urls.

Referenced by MC_AclAddReplyTo_chdl().

EXPORTMC int MC_AclDestroy ( struct fipa_acl_message_s * message )

Destroy a FIPA ACL message.

Parameters:: message The ACL message to destroy

Returns:: 0 on success, error code on failure.

Definition at line 72 of file libmc.c.

References fipa_acl_message_Destroy().

Referenced by MC_AclDestroy_chdl().

EXPORTMC struct fipa_acl_message_s* MC_AclNew ( void ) [read]

Allocate a new ACL Message.

Returns:: A newly allocated and empty ACL message.

Definition at line 78 of file libmc.c.

References fipa_acl_message_New().

Referenced by MC_AclNew_chdl().

EXPORTMC int MC_AclPost ( MCAgent_t agent,

struct fipa_acl_message_s * message

)

Post ACL message to agent.

Parameters:: agent The agent to post the message to

message The message to post

Returns:: 0 if successful, or error_code_t type.

Definition at line 83 of file libmc.c.

References agent_mailbox_Post(), and agent_s::mailbox.

Referenced by MC_AclPost_chdl(), and MC_AclSend().

EXPORTMC struct fipa_acl_message_s* MC_AclReply ( struct fipa_acl_message_s * acl_message ) [read]

Reply to an ACL message.

Parameters:: acl_message The incoming acl message to reply to

Returns:: A newly allocated ACL message

Note:: This function simply generates a new ACL message with the 'receiver' field automatically set to the 'sender' field of the incoming message.

Definition at line 89 of file libmc.c.

References fipa_Reply().

Referenced by MC_AclReply_chdl().

EXPORTMC struct fipa_acl_message_s* MC_AclRetrieve ( MCAgent_t agent ) [read]

Retrieve an ACL message.

Parameters:: agent Agent to retrieve message from.

Returns:: an ACL message struct on success or NULL on failure

Definition at line 95 of file libmc.c.

References agent_mailbox_Retrieve(), and agent_s::mailbox.

Referenced by MC_AclRetrieve_chdl().

EXPORTMC int MC_AclSend ( MCAgency_t attr,

struct fipa_acl_message_s * acl

)

Send a composed ACL Message.

Parameters:: attr An initialized and running MobileC agency

acl An allocated and fully composed ACL message.

Returns:: 0 if successful, error code on failure.

Definition at line 101 of file libmc.c.

References fipa_agent_identifier_s::addresses, mtp_http_s::content, mtp_http_content_s::content_type, mtp_http_content_s::data, dynstring_Destroy(), FIPA_ACL, fipa_acl_Compose(), fipa_agent_identifier_set_s::fipa_agent_identifiers, fipa_envelope_Compose(), mtp_http_s::host, http_to_hostport(), MC_AclPost(), MC_FindAgentByName(), dynstring_s::message, message_Destroy(), mtp_http_s::message_parts, message_Send(), message_s::message_type, mtp_http_CreateMessage(), mtp_http_Destroy(), mtp_http_New(), fipa_agent_identifier_s::name, fipa_url_sequence_s::num, fipa_agent_identifier_set_s::num, port, fipa_acl_message_s::receiver, fipa_url_s::str, mtp_http_s::target, message_s::target, and fipa_url_sequence_s::urls.

Referenced by MC_AclSend_chdl().

EXPORTMC int MC_AclSetContent ( struct fipa_acl_message_s * acl,

const char * content

)

Definition at line 300 of file libmc.c.

References fipa_string_s::content, fipa_acl_message_s::content, fipa_string_Destroy(), and fipa_string_New().

Referenced by MC_AclSetContent_chdl().

EXPORTMC int MC_AclSetPerformative ( struct fipa_acl_message_s * acl,

enum fipa_performative_e performative

)

Definition at line 198 of file libmc.c.

References fipa_acl_message_s::performative.

Referenced by MC_AclSetPerformative_chdl().

EXPORTMC int MC_AclSetSender ( struct fipa_acl_message_s * acl,

const char * name,

const char * address

)

Definition at line 206 of file libmc.c.

References fipa_agent_identifier_s::addresses, fipa_agent_identifier_Destroy(), fipa_agent_identifier_New(), fipa_url_New(), fipa_url_sequence_New(), fipa_agent_identifier_s::name, fipa_url_sequence_s::num, fipa_acl_message_s::sender, fipa_url_s::str, and fipa_url_sequence_s::urls.

Referenced by MC_AclSetSender_chdl().

EXPORTMC struct fipa_acl_message_s* MC_AclWaitRetrieve ( MCAgent_t agent ) [read]

Wait for and retrieve an ACL message.

Parameters:: agent Agent to retrieve message from.

Returns:: an ACL message struct on success or NULL on failure

Definition at line 191 of file libmc.c.

References agent_mailbox_WaitRetrieve(), and agent_s::mailbox.

Referenced by MC_AclWaitRetrieve_chdl().

EXPORTMC int MC_AddAgent ( MCAgency_t attr,

MCAgent_t agent

)

Add an agent to the agency 'attr'.

Parameters:: attr a MobileC agency

agent An initialized MobileC agent

Returns:: 0 if successful, or error_code_t type

Definition at line 317 of file libmc.c.

References mc_platform_s::agent_queue, mc_platform_s::ams, COND_SIGNAL, agency_s::mc_platform, agent_s::mc_platform, MUTEX_LOCK, and MUTEX_UNLOCK.

Referenced by MC_AddAgent_chdl().

const void* MC_AgentVariableRetrieve ( MCAgent_t agent,

const char * var_name,

int task_num

)

Retrieve a pointer to a previously saved variable.

Parameters:: agent A MobileC agent.

var_name The name of the saved variable that has previously been saved.

task_num The previous completed task from which to retrieve the saved variable.

Returns:: A pointer to the data on success or NULL on failure.

Examples

The following example demonstrates usage of MC_AgentVariableRetrieve() from agent space.

Definition at line 330 of file libmc.c.

References agent_task_s::agent_variable_list, interpreter_variable_data_s::data, agent_s::datastate, agent_datastate_s::task_progress, and agent_datastate_s::tasks.

Referenced by MC_AgentVariableRetrieve_chdl().

int MC_AgentVariableSave ( MCAgent_t agent,

const char * var_name

)

Mark an agent variable for saving.

Parameters:: agent A MobileC agent.

var_name The name of the variable to mark for saving.

Returns:: 0 on success, non-zero on failure.

See also:: test1.xml

Examples

See agent_saved_variables_example/test1.xml for an example of usage of this api function.

Examples

The following example demonstrates usage of MC_AgentVariableSave() from agent space.

Definition at line 348 of file libmc.c.

References agent_s::datastate, MC_ERR_MEMORY, agent_task_s::num_saved_variables, agent_task_s::saved_variables, agent_datastate_s::task_progress, and agent_datastate_s::tasks.

Referenced by MC_AgentVariableSave_chdl().

EXPORTMC int MC_BarrierDelete ( MCAgency_t attr,

int id

)

Find and delete an initialized MobileC Barrier.

Parameters:: attr A running MobileC agency

id The id of the barrier node to delete

Returns:: returns 0 on success, error if the node is not found or other failure.

Definition at line 409 of file libmc.c.

References mc_platform_s::barrier_queue, barrier_queue_Delete(), and agency_s::mc_platform.

Referenced by MC_BarrierDelete_chdl().

EXPORTMC int MC_BarrierInit ( MCAgency_t attr,

int id,

int num_procs

)

Initialize a MobileC Barrier.

Parameters:: attr A running MobileC agency

id The requested barrier id

num_procs The number of agents/threads/processes that will wait on the barrier

Returns:: The allocated barrier id. May differ from the requested id if it is alread in use.

Examples

The following example demonstrates an agent which sets up an MC_Barrier.

Definition at line 395 of file libmc.c.

References barrier_node_Initialize(), mc_platform_s::barrier_queue, barrier_queue_Add(), barrier_queue_Get(), MC_ERR, agency_s::mc_platform, MC_SUCCESS, and node.

Referenced by MC_BarrierInit_chdl().

EXPORTMC int MC_CallAgentFunc ( MCAgent_t agent,

const char * funcName,

void * returnVal,

int numArgs,

...

)

Calls a function defined in an agent.

Parameters:: agent An initialized and executed MobileC agent

funcName The name of the function to call

returnVal The agent function's return value

numArgs The number of arguments supplied to the agent function

... A variable argument list to be supplied to the agent function

Returns:: 0 if successful, error_code_t type on failure

Example

Definition at line 415 of file libmc.c.

References agent_s::agent_interp, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::run_lock.

EXPORTMC int MC_CallAgentFuncArg ( MCAgent_t agent,

const char * funcName,

void * returnVal,

void * arg

)

Calls a function defined in an agent.

Parameters:: agent An initialized and executed MobileC agent

funcName The name of the function to call

returnVal The agent function's return value

arg The agent functions argument

Note:: The agent function must be of the form 'void* func(void* arg);'

Returns:: 0 if successful, error_code_t type on failure

Example

Definition at line 436 of file libmc.c.

References agent_s::agent_interp, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::run_lock.

EXPORTMC int MC_CallAgentFuncV ( MCAgent_t agent,

const char * funcName,

void * returnVal,

va_list ap

)

Calls a function defined in an agent.

Parameters:: agent An initialized and executed MobileC agent

funcName The name of the function to call

returnVal The agent function's return value

ap A variable argument list

Returns:: 0 if successful, error_code_t type on failure

Definition at line 455 of file libmc.c.

References agent_s::agent_interp, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::run_lock.

EXPORTMC int MC_CallAgentFuncVar ( MCAgent_t agent,

const char * funcName,

void * returnVal,

ChVaList_t arglist

)

Definition at line 475 of file libmc.c.

References agent_s::agent_interp, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::run_lock.

Referenced by MC_CallAgentFunc_chdl().

EXPORTMC int MC_ChInitializeOptions ( MCAgency_t attr,

ChOptions_t * options

)

Use custom ChOptions_t type for internal Ch interpretor.

Parameters:: attr A running MobileC agency

options Initialized Ch options structure

Returns:: 0 on success, error_code_t type on failure

Definition at line 495 of file libmc.c.

References mc_platform_s::interp_options, and agency_s::mc_platform.

MCAgent_t MC_ComposeAgent ( const char * name,

const char * home,

const char * owner,

const char * code,

const char * return_var_name,

const char * server,

int persistent

)

Compose a new agent dynamically without using a prewritten XML file.

Parameters:: name The desired name of the new agent.

home The home of the new agent.

owner The owner of the new agent.

code The agent code

return_var_name The name of the agent's return variable. Set to "no-return" if no return variable is desired.

server The target destination of the agent.

persitent A flag indicating whether or not the agent should be persistent. A value of '1' indicates persistence, while a value of '0' indicates default non-persistent behaviour.

Returns:: This function returns a valid MCAgent_t structure on success or NULL on failure.

Definition at line 513 of file libmc.c.

References agent_datastate_s::agent_code, agent_datastate_s::agent_code_ids, agent_datastate_s::agent_codes, agent_datastate_New(), agent_New(), agent_s::agent_status, agent_task_New(), agent_s::agent_type, agent_s::datastate, agent_s::home, MC_LOCAL_AGENT, MC_WAIT_MESSGSEND, agent_s::name, agent_datastate_s::number_of_tasks, agent_s::orphan, agent_s::owner, agent_datastate_s::persistent, agent_task_s::server_name, agent_datastate_s::tasks, and agent_task_s::var_name.

Referenced by MC_ComposeAgent_chdl().

EXPORTMC int MC_CondBroadcast ( MCAgency_t attr,

int id

)

Wakes up all agents/threads waiting on a condition variable.

Parameters:: attr A MobileC agency

id Synchronization variable id to broadcast to

See also:: MC_SyncInit(), MC_CondSignal()

Returns:: 0 on success, error_code_t type on failure

Definition at line 583 of file libmc.c.

References syncListNode_s::cond, COND_BROADCAST, syncListNode_s::lock, MC_ERR_NOT_FOUND, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, syncListNode_s::signalled, mc_platform_s::syncList, and syncListFind().

Referenced by MC_CondBroadcast_chdl().

EXPORTMC int MC_CondReset ( MCAgency_t attr,

int id

)

Reset a previously signalled MobileC condition variable.

Parameters:: attr A MobileC Agency

id The synchronization variable id to reset

See also:: MC_SyncInit()

Returns:: 0 on success, error_code_t type on failure

Definition at line 635 of file libmc.c.

References syncListNode_s::lock, MC_ERR_NOT_FOUND, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, syncListNode_s::signalled, mc_platform_s::syncList, and syncListFind().

Referenced by MC_CondReset_chdl().

EXPORTMC int MC_CondSignal ( MCAgency_t attr,

int id

)

Wakes up at least one thread waiting on a condition variable.

Parameters:: attr A MobileC agency

id synchronization variable id

See also:: MC_SyncInit()

Returns:: 0 on success, error_code_t type on failure

Example

The following example demonstrates the agent-space version of the function, which is nearly identical to the binary space api function.

Definition at line 598 of file libmc.c.

References syncListNode_s::cond, COND_SIGNAL, syncListNode_s::lock, MC_ERR_NOT_FOUND, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, syncListNode_s::signalled, mc_platform_s::syncList, and syncListFind().

Referenced by MC_CondSignal_chdl().

EXPORTMC int MC_CondWait ( MCAgency_t attr,

int id

)

Wait on a MobileC synchronization variable.

Parameters:: attr A MobileC agency

id a synchronization variable id

See also:: MC_SyncInit()

Returns:: 0 on success, error_code_t type on failure

Example

The following example demonstrates the agent-space version of this function.

Definition at line 613 of file libmc.c.

References syncListNode_s::cond, COND_WAIT, syncListNode_s::lock, MC_ERR_NOT_FOUND, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, syncListNode_s::signalled, mc_platform_s::syncList, and syncListFind().

Referenced by MC_CondWait_chdl().

int MC_CopyAgent ( MCAgent_t * agent_out,

const MCAgent_t agent_in

)

Performs a deep-copy of an agent structure.

Parameters:: agent_out A pointer to the agent to copy to.

agent_in The agent to copy

Returns:: 0 on success, error_code_t type on failure.

Definition at line 653 of file libmc.c.

References agent_Copy(), and MC_SUCCESS.

EXPORTMC int MC_DeleteAgent ( MCAgent_t agent )

Stop and remove an agent.

Parameters:: agent An agent in any state (running, waiting, etc)

Returns:: 0 on success, error_code_t type on failure

Definition at line 660 of file libmc.c.

References CHECK_NULL, MC_ERR_INVALID, MC_SetAgentStatus(), MC_SUCCESS, MC_TerminateAgent(), and MC_WAIT_FINISHED.

Referenced by MC_DeleteAgent_chdl().

int MC_DestroyServiceSearchResult ( char ** agentName,

char ** serviceName,

int * agentID,

int numResult

)

Free memory allocated by a Service Search operation.

Parameters:: agentName agent names returned by a search operation.

serviceName service names return by a search operation.

agentID list of agent id's returned by a search operation.

numResult The number of hits returned by a search operation.

Returns:: 0 on success, error code on failure.

Definition at line 674 of file libmc.c.

Referenced by MC_DestroyServiceSearchResult_chdl().

EXPORTMC int MC_End ( MCAgency_t attr )

End an agency.

Parameters:: attr A running agency

Returns:: 0 on success, error_code_t type on failure

Example

Definition at line 723 of file libmc.c.

References mc_platform_s::acc, mc_platform_s::ams, mc_platform_s::cmd_prompt, COND_SIGNAL, mc_platform_s::connection_queue, mc_platform_s::df, GET_THREAD_MODE, agency_s::hostName, agency_s::mc_platform, mc_platform_Destroy(), MC_THREAD_ACC, MC_THREAD_AMS, MC_THREAD_CP, MC_THREAD_DF, mc_platform_s::message_queue, MUTEX_LOCK, MUTEX_UNLOCK, mc_platform_s::quit, mc_platform_s::quit_lock, cmd_prompt_s::thread, THREAD_CANCEL, THREAD_JOIN, and agency_s::threads.

Referenced by MC_End_chdl().

EXPORTMC MCAgent_t MC_FindAgentByID ( MCAgency_t attr,

int ID

)

Find an agent by its id.

Parameters:: attr the agency to search

ID the id to search for

Returns:: a valid agent on success, NULL on failure

Definition at line 790 of file libmc.c.

References mc_platform_s::agent_queue, and agency_s::mc_platform.

Referenced by MC_FindAgentByID_chdl().

EXPORTMC MCAgent_t MC_FindAgentByName ( MCAgency_t attr,

const char * name

)

Find an agent by its name.

Parameters:: attr a running agency

name name to search for

Returns:: a valid agent on success or NULL on failure

Example

Definition at line 777 of file libmc.c.

References mc_platform_s::agent_queue, and agency_s::mc_platform.

Referenced by MC_AclSend(), and MC_FindAgentByName_chdl().

EXPORTMC void* MC_GetAgentExecEngine ( MCAgent_t agent )

Retrieve an agent's Ch interpreter.

Parameters:: agent a valid agent

Returns:: a Ch interpreter of type 'ChInterp_t' on success, or NULL on failure.

Definition at line 844 of file libmc.c.

References agent_s::agent_interp.

EXPORTMC int MC_GetAgentID ( MCAgent_t agent )

Retrieve an agent's id.

Definition at line 850 of file libmc.c.

References agent_s::id.

Referenced by MC_GetAgentID_chdl().

EXPORTMC char* MC_GetAgentName ( MCAgent_t agent )

Definition at line 858 of file libmc.c.

References agent_s::lock, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::name.

Referenced by MC_GetAgentName_chdl().

EXPORTMC int MC_GetAgentNumTasks ( MCAgent_t agent )

Retrive the number of tasks an agent has.

Example

Definition at line 939 of file libmc.c.

References agent_s::datastate, and agent_datastate_s::number_of_tasks.

Referenced by MC_GetAgentNumTasks_chdl().

EXPORTMC int MC_GetAgentReturnData ( MCAgent_t agent,

int task_num,

void ** data,

int * dim,

int ** extent

)

Get an agent's return data.

Parameters:: agent a valid agent

task_num the task for which to retrieve the return data. The task must already be completed.

data the return data. May be multi dimensional array.

dim the number of dimensions of the return array.

extent the extent of each one of the array dimensions.

Example

This file demonstrates the retrieval of agent return data from an agent

This is the agent which gets the data

Definition at line 876 of file libmc.c.

References agent_task_s::agent_return_data, interpreter_variable_data_s::array_dim, interpreter_variable_data_s::array_extent, CH_DATATYPE_SIZE, interpreter_variable_data_s::data_type, agent_s::datastate, agent_datastate_s::number_of_tasks, size, and agent_datastate_s::tasks.

EXPORTMC int MC_GetAgentStatus ( MCAgent_t agent )

Get an agent's current status.

Returns:: returns type 'enum MC_AgentStatus_e'

Definition at line 822 of file libmc.c.

References agent_s::agent_status, agent_s::lock, MUTEX_LOCK, and MUTEX_UNLOCK.

Referenced by MC_GetAgentStatus_chdl().

EXPORTMC enum MC_AgentType_e MC_GetAgentType ( MCAgent_t agent )

Get an agent's type.

Returns:: returns type 'enum MC_AgentType_e'

Definition at line 945 of file libmc.c.

References agent_s::agent_type.

EXPORTMC char* MC_GetAgentXMLString ( MCAgent_t agent )

Get an agent's xml string.

Returns:: a malloc'd character string containing the agent's xml code

Definition at line 832 of file libmc.c.

References agent_s::datastate, mxmlSaveAllocString(), and agent_datastate_s::xml_agent_root.

Referenced by MC_GetAgentXMLString_chdl().

EXPORTMC int MC_HaltAgency ( MCAgency_t agency )

Halt an agency: Do not process new entries in queues.

Parameters:: agency A handle to a running MobileC agency.

Returns:: 0 on success, non-zero on failure.

Definition at line 991 of file libmc.c.

References mc_platform_s::giant, mc_platform_s::giant_lock, agency_s::mc_platform, MUTEX_LOCK, and MUTEX_UNLOCK.

Referenced by MC_GetAllAgents(), and MC_HaltAgency_chdl().

EXPORTMC MCAgency_t MC_Initialize ( int port,

MCAgencyOptions_t * options

)

Initialize and start a MobileC agency.

Parameters:: port the TCP port the agency should bind to

options initialized MobileC options or NULL for default options

Returns:: a handle to a running MobileC agency or NULL on failure

Example

Definition at line 1000 of file libmc.c.

References CHECK_NULL, agency_s::client, MCAgencyOptions_s::default_agent_status, agency_s::default_agentstatus, MCAgencyOptions_s::enable_security, agency_s::enable_security, HOST_NAME_MAX, agency_s::hostName, MC_InitializeAgencyOptions(), agency_s::mc_platform, mc_platform_Initialize(), MC_THREAD_ALL, agency_s::portno, agency_s::server, MCAgencyOptions_s::stack_size, agency_s::stack_size, MCAgencyOptions_s::threads, and agency_s::threads.

EXPORTMC int MC_InitializeAgencyOptions ( struct MCAgencyOptions_s * options )

Initialize MobileC options.

Parameters:: options options to initialize.

Returns:: 0 on success, error_code_t on failure

Note:: MobileC options should be initialized with this function before any of its members are modified.

Example

Definition at line 1055 of file libmc.c.

References MCAgencyOptions_s::default_agent_status, MCAgencyOptions_s::enable_security, MC_THREAD_ALL, MC_WAIT_CH, MCAgencyOptions_s::modified, MCAgencyOptions_s::stack_size, and MCAgencyOptions_s::threads.

Referenced by MC_Initialize().

EXPORTMC int MC_LoadAgentFromFile ( MCAgency_t attr,

const char * filename

)

Load an agent from a file into an agency.

Parameters:: agency A valid and running Mobile-C agency

filename Filename containing the agent to load

Returns:: 0 on success, non-zero on failure.

Definition at line 1072 of file libmc.c.

References buf, agency_s::mc_platform, message_Destroy(), message_InitializeFromString(), message_New(), mc_platform_s::message_queue, MXML_DESCEND, mxmlFindElement(), mxmlLoadString(), message_s::to_address, message_s::xml_payload, and message_s::xml_root.

EXPORTMC int MC_MainLoop ( MCAgency_t attr )

Wait indefinitely.

Note:: This function is intended to block the calling thread forever.

Definition at line 1697 of file libmc.c.

References mc_platform_s::ams, and agency_s::mc_platform.

EXPORTMC int MC_MutexLock ( MCAgency_t attr,

int id

)

Locks a MobileC synchronization variable as a mutex.

Parameters:: attr a MobileC agency handle

id the synchronization variable id to lock

Returns:: 0 on success, error_code_t type on failure

Example

Consider the following agents, which use the agent-space version of this api function. Note that the 'sleep' agent is sent first, followed by the 'wake' agent.

Definition at line 1142 of file libmc.c.

References syncListNode_s::lock, agency_s::mc_platform, MUTEX_LOCK, mc_platform_s::syncList, and syncListFind().

Referenced by MC_MutexLock_chdl().

EXPORTMC int MC_MutexUnlock ( MCAgency_t attr,

int id

)

Definition at line 1154 of file libmc.c.

References syncListNode_s::lock, agency_s::mc_platform, MUTEX_UNLOCK, mc_platform_s::syncList, and syncListFind().

Referenced by MC_MutexUnlock_chdl().

EXPORTMC int MC_PrintAgentCode ( MCAgent_t agent )

Prints an agents code to stdout.

Returns:: 0 on success, error_code_t on failure

Definition at line 1166 of file libmc.c.

References agent_datastate_s::agent_code, agent_s::datastate, agent_s::lock, MUTEX_LOCK, MUTEX_UNLOCK, agent_datastate_s::number_of_tasks, and agent_datastate_s::task_progress.

Referenced by MC_PrintAgentCode_chdl().

EXPORTMC int MC_RegisterService ( MCAgency_t agency,

MCAgent_t agent,

int agentID,

const char * agentName,

char ** serviceNames,

int numServices

)

Parameters:: agency a MobileC agency handle

agent (OPTIONAL: See note) a MobileC agent

agentID (OPTIONAL: See note) a MobileC agent id

agentName (OPTIONAL: See note) a MobileC agent name

serviceNames an array of character strings of service names

numServices the number of services described in 'serviceNames'

Returns:: 0 on success, error_code_t type on failure

Note:: Three of the input arguments are optional. The function expects as input the arguments 'agent XOR (agentID AND agentName)'.

Example

Definition at line 1182 of file libmc.c.

References CHECK_NULL, mc_platform_s::df, df_AddRequest(), df_request_list_node_New(), agent_s::id, MC_ERR_INVALID_ARGS, MC_ERR_MEMORY, agency_s::mc_platform, MUTEX_INIT, MUTEX_T, and agent_s::name.

Referenced by MC_RegisterService_chdl().

EXPORTMC int MC_ResetSignal ( MCAgency_t attr )

Reset a MobileC signal.

Returns:: 0 on success, error_code_t on failure

See also:: MC_WaitSignal()

Definition at line 1316 of file libmc.c.

References COND_SIGNAL, mc_platform_s::giant, mc_platform_s::giant_cond, mc_platform_s::giant_lock, MC_NO_SIGNAL, agency_s::mc_platform, mc_platform_s::MC_signal, MUTEX_LOCK, and MUTEX_UNLOCK.

EXPORTMC int MC_ResumeAgency ( MCAgency_t agency )

Resumes a halted agency.

Parameters:: agency An agency previously halted with the MC_HaltAgency() function.

Returns:: 0 on success, non-zero on failure.

Definition at line 1261 of file libmc.c.

References mc_platform_s::giant, mc_platform_s::giant_lock, agency_s::mc_platform, MUTEX_LOCK, and MUTEX_UNLOCK.

Referenced by MC_GetAllAgents(), and MC_ResumeAgency_chdl().

EXPORTMC MCAgent_t MC_RetrieveAgent ( MCAgency_t attr )

Retrieves the oldest agent from an agency.

Returns:: a valid agent or NULL on failure

Definition at line 1270 of file libmc.c.

References mc_platform_s::agent_queue, agent_s::agent_status, ListSearch(), MC_AGENT_NEUTRAL, agency_s::mc_platform, MUTEX_LOCK, and MUTEX_UNLOCK.

Referenced by MC_RetrieveAgent_chdl().

EXPORTMC char* MC_RetrieveAgentCode ( MCAgent_t agent )

Retrieves an agent's Ch code.

Returns:: a malloc'd character string on success, NULL on failure

Definition at line 1300 of file libmc.c.

References agent_datastate_s::agent_code, buf, agent_s::datastate, agent_s::lock, MUTEX_LOCK, MUTEX_UNLOCK, and agent_datastate_s::task_progress.

Referenced by MC_RetrieveAgentCode_chdl().

EXPORTMC int MC_SearchForService ( MCAgency_t attr,

const char * searchString,

char *** agentNames,

char *** serviceNames,

int ** agentIDs,

int * numResults

)

Search the directory facilitator for a service.

Returns:: 0 on success, error_code_t on failure

Parameters:: attr (input) a MobileC agency handle

searchString (input) substring to search services for

agentNames (return) array of agent names with matching services

serviceNames (return) array of matching service names

agentIDs (return) array of matching agent IDs

numResults (return) number of matching results

Example

Definition at line 1327 of file libmc.c.

References CHECK_NULL, COND_SLEEP_ACTION, mc_platform_s::df, df_AddRequest(), df_request_list_node_Destroy(), df_request_list_node_New(), df_request_search_Destroy(), df_request_search_New(), MC_ERR_MEMORY, agency_s::mc_platform, MC_SUCCESS, and search.

Referenced by MC_SearchForService_chdl().

EXPORTMC int MC_SemaphorePost ( MCAgency_t attr,

int id

)

Post to a MobileC synchronization variable semaphore.

Parameters:: attr a MobileC agency handle

id the synchronization variable id to post to

Returns:: 0 on success, error_code_t type on failure

Example

Definition at line 1377 of file libmc.c.

References agency_s::mc_platform, syncListNode_s::sem, SEMAPHORE_POST, mc_platform_s::syncList, and syncListFind().

Referenced by MC_SemaphorePost_chdl().

EXPORTMC int MC_SemaphoreWait ( MCAgency_t attr,

int id

)

Decreases a MobileC synchronization variable semaphore count by one.

Parameters:: attr a MobileC agency handle

id synchronization variable id to wait on

Returns:: 0 on MC_SUCCESS, error_code_t type of failure

Note:: If the semaphore count is already zero, this function will block until another thread posts to the semaphore.

Example

Definition at line 1389 of file libmc.c.

References agency_s::mc_platform, syncListNode_s::sem, SEMAPHORE_WAIT, mc_platform_s::syncList, and syncListFind().

Referenced by MC_SemaphoreWait_chdl().

EXPORTMC int MC_SendAgentMigrationMessage ( MCAgency_t attr,

const char * message,

const char * hostname,

int port

)

Sends an agent migration message.

Parameters:: attr a MobileC agency handle

message a valid MobileC xml agent migration message

hostname host to send the message to

port port to send the message to

Definition at line 1411 of file libmc.c.

References MC_ERR, agency_s::mc_platform, message_Destroy(), message_InitializeFromString(), message_New(), and mc_platform_s::message_queue.

Referenced by MC_SendAgentMigrationMessage_chdl().

EXPORTMC int MC_SendAgentMigrationMessageFile ( MCAgency_t attr,

const char * filename,

const char * hostname,

int port

)

Sends an agent migration message.

Parameters:: attr a MobileC agency handle

filename file containing a valid MobileC xml agent migration message

hostname hostname to send the agent to

port port to send the agent to

Definition at line 1442 of file libmc.c.

References buf, agency_s::mc_platform, message_Destroy(), message_InitializeFromString(), message_New(), and mc_platform_s::message_queue.

Referenced by handler_SEND(), and MC_SendAgentMigrationMessageFile_chdl().

EXPORTMC int MC_SetAgentStatus ( MCAgent_t agent,

int status

)

Set an agent's status.

Parameters:: agent a MobileC agent

status agent status of type 'enum MC_AgentStatus_e'

Returns:: 0 on success, or error_code_t on failure

Definition at line 1528 of file libmc.c.

References agent_s::agent_status, mc_platform_s::ams, COND_SIGNAL, agent_s::lock, agent_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, and agent_s::orphan.

Referenced by MC_DeleteAgent(), and MC_SetAgentStatus_chdl().

EXPORTMC int MC_SetDefaultAgentStatus ( MCAgency_t agency,

enum MC_AgentStatus_e status

)

Sets default incoming agent status.

Parameters:: agency a MobileC agency handle

status the status to set all incoming agents

Returns:: 0 on success, error_type_t on failure

Note:: using this function will override any status the incoming agent attempts to set for itself.

Definition at line 1543 of file libmc.c.

References mc_platform_s::default_agentstatus, and agency_s::mc_platform.

Referenced by MC_SetDefaultAgentStatus_chdl().

EXPORTMC int MC_SetThreadOff ( MCAgencyOptions_t * options,

enum MC_ThreadIndex_e index

)

Sets a MobileC thread to "off" status.

Parameters:: options MobileC options previously initialized with MC_InitializeAgencyOptions()

index the thread to set

Returns:: 0 on success, error_code_t on failure

Note:: This function must be called before MC_Initialize(). Once an agency is started with MC_Initialize, the MC_SetThread functions will have no effect.

Definition at line 1570 of file libmc.c.

References SET_THREAD_OFF, and MCAgencyOptions_s::threads.

EXPORTMC int MC_SetThreadOn ( MCAgencyOptions_t * options,

enum MC_ThreadIndex_e index

)

Sets a MobileC thread to "on" status.

Parameters:: options MobileC options previously initialized with MC_InitializeAgencyOptions()

index the thread to set

Returns:: 0 on success, error_code_t on failure

Note:: This function must be called before MC_Initialize(). Once an agency is started with MC_Initialize, the MC_SetThread functions will have no effect.

Definition at line 1553 of file libmc.c.

References SET_THREAD_ON, and MCAgencyOptions_s::threads.

EXPORTMC int MC_SetThreadsAllOff ( MCAgencyOptions_t * options )

Set all MobileC threads to 'off' status.

Parameters:: options a MobileC options structure initialized with with the MC_InitializeAgencyOptions() function.

Returns:: 0 on success, error code on failure.

Definition at line 1577 of file libmc.c.

References MC_THREAD_ALL, SET_THREAD_OFF, and MCAgencyOptions_s::threads.

EXPORTMC int MC_SetThreadsAllOn ( MCAgencyOptions_t * options )

Set all Mobile-C threads on.

Parameters:: options MobileC options structure, initialized with MC_InitializeAgencyOptions()

Returns:: 0 on success, error code on failure.

Definition at line 1560 of file libmc.c.

References MC_THREAD_ALL, SET_THREAD_ON, and MCAgencyOptions_s::threads.

EXPORTMC int MC_Steer ( MCAgency_t attr,

int(*)(void *data) funcptr,

void * arg

)

Set up a steerable algorithm.

Parameters:: attr a MobileC agency handle

funcptr a function pointer to the algorithm

arg an argument for the algorithm function

Returns:: 0 on success, error_code_t on failure

Note:: The algorithm function must contain a call to MC_SteerControl in order for the algorithm to be steerable.

Example

Definition at line 1587 of file libmc.c.

References agency_s::mc_platform, MC_RESTART, MC_RUN, mc_platform_s::MC_steer_command, mc_platform_s::MC_steer_lock, MUTEX_LOCK, and MUTEX_UNLOCK.

EXPORTMC enum MC_SteerCommand_e MC_SteerControl ( void )

The MobileC user-algorithm steering function.

Returns:: The current steering command

Note:: This function belongs inside a user's steerable algorithm.

See also:: MC_Steer()

Definition at line 1606 of file libmc.c.

References COND_WAIT, mc_platform_s::MC_steer_command, mc_platform_s::MC_steer_cond, mc_platform_s::MC_steer_lock, MC_SUSPEND, MUTEX_LOCK, and MUTEX_UNLOCK.

EXPORTMC int MC_SyncDelete ( MCAgency_t attr,

int id

)

Deletes a previously initialized synchronization variable.

Parameters:: attr a MobileC agency handle

id the sync variable id to delete

Returns:: 0 on success, or error_code_t on failure

Definition at line 1622 of file libmc.c.

References syncList_s::giant_lock, syncListNode_s::lock, MC_ERR_NOT_FOUND, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, mc_platform_s::syncList, syncListFind(), syncListNodeDestroy(), and syncListRemove().

Referenced by MC_SyncDelete_chdl().

EXPORTMC int MC_SyncInit ( MCAgency_t attr,

int id

)

Initializes a new MobileC synchronization variable.

Parameters:: attr a MobileC agency handle

id the requested sync variable id

Returns:: new sync variable's id. May be different than the requested id.

Note:: Each synchronization variable may be used as a mutex, condition variable, or semaphore. However, it should only be used as one type of synchronization variable per instance, or undefined behaviour may result.

See also:: MC_MutexLock(), MC_MutexUnlock(), MC_CondWait(), MC_CondSignal(), MC_CondBroadcast, MC_SemaphorePost(), MC_SemaphoreWait()

Definition at line 1652 of file libmc.c.

References syncList_s::giant_lock, syncListNode_s::id, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, node, mc_platform_s::syncList, syncListAddNode(), syncListFind(), and syncListNodeNew().

Referenced by MC_SyncInit_chdl().

EXPORTMC int MC_TerminateAgent ( MCAgent_t agent )

Halt a running agent.

Returns:: 0 on success, error_code_t on failure

Definition at line 1677 of file libmc.c.

References agent_s::agent_interp.

Referenced by MC_DeleteAgent(), and MC_TerminateAgent_chdl().

EXPORTMC int MC_WaitAgent ( MCAgency_t attr )

Wait indefinitely.

Note:: This function is intended to block the calling thread forever. Wait for an agent arrival event
This function blocks until an agent arrival signal is triggered, at which point in unblocks.

Definition at line 1704 of file libmc.c.

References mc_platform_s::agent_queue, COND_WAIT, mc_platform, agency_s::mc_platform, MUTEX_LOCK, MUTEX_UNLOCK, and size.