LibMC.MCAgency Class Reference

Wrapper class for MCAgency_t structure. More...

List of all members.

Public Types
enum	MCAgencyState
	Enum for describing the state of the agency. More...
enum	ChShellType
	Ch shell type. More...
enum	MC_ThreadIndex_e
	Enum for describing the different threads that Mobile-C uses. More...
enum	MC_SteerCommand_e
	Available commands for MC_Steer. More...
Public Member Functions
	MCAgency ()
	Default constructor.
int	Initialize ()
	Starts the agency.
int	End ()
	Stops and destroys the agency.
int	ChInitializeOptions (ChShellType shellType, String home)
	Initializes Ch options for the agency.
int	SetThreadsAllOff ()
	Sets all threads for the agency to "off.".
int	SetThreadOn (MC_ThreadIndex_e index)
	Sets an individual thread for the agency to "on.".
int	SetThreadOff (MC_ThreadIndex_e index)
	Sets an individual thread for the agency to "off.".
int	HaltAgency ()
	Temporarily halts the agency.
int	ResumeAgency ()
	Resumes a halted agency.
int	SetDefaultAgentStatus (MCAgent.MC_AgentStatus_e status)
	Sets the default state of an agent in the agency.
MCAgent	WaitRetrieveAgent ()
	Waits for an agent to arrive and returns the agent.
int	WaitAgent ()
	Waits for an agent to arrive.
int	SendAgentMigrationMessageFile (String filename, String hostname, int port)
	Sends an agent migration message file to an agency.
int	LoadAgentMigrationMessageFile (String filename)
	Load an agent migration message.
int	SendAgentMigrationMessage (String message, String hostname, int port)
	Sends an agent migration message to an agency.
int	CondBroadcast (int id)
	Broadcast a condition signal.
int	CondSignal (int id)
	Signal a condition.
int	CondReset (int id)
	Reset a condition signal.
int	CondWait (int id)
	Wait for a condition signal.
int	MutexLock (int id)
	Lock a mutex.
int	MutexUnlock (int id)
	Unlock a mutex.
int	SemaphorePost (int id)
	Posts a semaphore.
int	SemaphoreWait (int id)
	Wait for a semaphore to be posted.
int	ResetSignal ()
	Reset an agency signal.
int	SyncDelete (int id)
	Delete a synchronization variable.
int	SyncInit (int id)
	Create a new synchronization variable.
int	WaitSignal (int signals)
	Wait for agency signals.
int	BarrierDelete (int id)
	Delete a barrier object.
int	BarrierInit (int id, int num_procs)
	Create a new barrier.
MC_SteerCommand_e	SteerControl ()
	Steering control function.
int	Steer (IntPtr funcptr, IntPtr arg)
	Steering control function.
int	RegisterService (MCAgent agent, int agentID, String agentName, String[] serviceNames, int numServices)
	Registers services in the agency.
int	SearchForService (String searchString, IntPtr agentNames, IntPtr serviceNames, IntPtr agentIDs, IntPtr numResults)
	Searches for services in the agency.
int	AddAgent (MCAgent agent)
	Add an agent to the agency.
MCAgent	FindAgentByName (String name)
	Finds an agent by its name.
MCAgent	FindAgentByID (int id)
	Find an agent by its ID.
MCAgent	RetrieveAgent ()
	Retrieve an agent from the agency.
int	AclSend (MCAclMessage acl_message)
	Send an ACL message to the agency.
int	MainLoop ()
	Makes the agency wait indefinitely.
Properties
int	Port [get, set]
	Accessor for the port number of the agency.
MCAgencyState	State [get]
	Accessor for the agency state.

---

Detailed Description

Wrapper class for MCAgency_t structure.

This class provides an interface to the Mobile-C agency. Member functions for the class are generally overloaded versions of the respective functions in the Mobile-C library. The class maintains a pointer to the Mobile-C agency in unmanaged memory. The pointer is not accessible by the user.

Definition at line 329 of file MCAgency.cs.

---

Member Enumeration Documentation

enum LibMC::MCAgency::MCAgencyState

Enum for describing the state of the agency.

This enum is used to determine whether or not certain actions should be permitted, such as halting, resuming, and ending an agency

Enumerator:

NoState	Default, uninitialized state
Initialized	Agency initialized, but not started
Running	Agency is running
Halted	Agency has been stopped (can be resumed)
Ended	Agency is stopped (destroyed)

Definition at line 337 of file MCAgency.cs.

enum LibMC::MCAgency::ChShellType

Ch shell type.

Used to set the shell type for the Ch interpretter.

Enumerator:

CH_REGULARCH	Default, regular shell
CH_SAFECH	Safe shell

Definition at line 351 of file MCAgency.cs.

enum LibMC::MCAgency::MC_ThreadIndex_e

Enum for describing the different threads that Mobile-C uses.

These enums can be used to turn threads on and off before an agency is initialized.

Note:

This enum is pulled directly from the Mobile-C library.

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

Definition at line 79 of file MCExports.cs.

enum LibMC::MCAgency::MC_SteerCommand_e

Available commands for MC_Steer.

Note:

This enum is pulled directly from the Mobile-C library.

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 94 of file MCExports.cs.

---

Constructor & Destructor Documentation

LibMC.MCAgency.MCAgency

(

)

Default constructor.

The default constructor for the MCAgency class. It creates a new agency, default options for the agency, and initializes the agency. It does not start the agency.

Definition at line 369 of file MCAgency.cs.

---

Member Function Documentation

int LibMC.MCAgency.Initialize

(

)

Starts the agency.

Starts the agency and sets the agency state.

Returns:

0 on success, -1 on failure.

Note:

The agency port and any other options must be set before calling this function.

Definition at line 445 of file MCAgency.cs.

int LibMC.MCAgency.End

(

)

Stops and destroys the agency.

Stops the agency and sets the agency state appropriately.

Returns:

The return value of the underlying MC_End function.

Note:

This call will fail if the underlying Mobile-C agency is not in the correct state.

Definition at line 467 of file MCAgency.cs.

int LibMC.MCAgency.ChInitializeOptions	(	ChShellType	shellType,
		String	home
	)

Initializes Ch options for the agency.

Can be used to set the home directory and shell mode for the Ch interpretter.

Parameters:

	shellType	The type of shell Ch should use: CH_REGULARCH or CH_SAFECH.
	home	The home directory Ch should use.

Returns:

The return value of the underlying MC_ChInitializeOptions function.

Note:

This function must be called before the agency is started.

Definition at line 485 of file MCAgency.cs.

int LibMC.MCAgency.SetThreadsAllOff

(

)

Sets all threads for the agency to "off.".

Sets all threads for the agency to "off." Not recommended for use.

Returns:

The return value of the underlying MC_SetThreadsAllOff function.

Note:

This function must be called before the agency is started.

Definition at line 516 of file MCAgency.cs.

int LibMC.MCAgency.SetThreadOn

(

MC_ThreadIndex_e

index

)

Sets an individual thread for the agency to "on.".

Threads are on by default. If they have been turned off, this function turns them on again.

Parameters:

index

The enum that identifies the thread to be turned on.

Returns:

The return value of the underlying MC_SetThreadOn function.

Note:

This function must be called before the agency is started.

Definition at line 532 of file MCAgency.cs.

int LibMC.MCAgency.SetThreadOff

(

MC_ThreadIndex_e

index

)

Sets an individual thread for the agency to "off.".

Most commonly used to turn the command prompt thread off.

Parameters:

index

The enum that identifies the thread to be turned off.

Returns:

The return value of the underlying MC_SetThreadOff function.

Note:

This function must be called before the agency is started.

Definition at line 547 of file MCAgency.cs.

int LibMC.MCAgency.HaltAgency

(

)

Temporarily halts the agency.

Halts the agency until it is resumed or ended.

Returns:

The return value of the underlying MC_HaltAgency function.

Note:

The underlying Mobile-C agency must be in the correct state to call this function or it will fail.

Definition at line 562 of file MCAgency.cs.

int LibMC.MCAgency.ResumeAgency

(

)

Resumes a halted agency.

Resumes a halted agency. Cannot be used on ended agencies.

Returns:

The return value of the underlying MC_ResumeAgency function.

Note:

The underlying Mobile-C agency must be in the correct state to call this function or it will fail.

Definition at line 579 of file MCAgency.cs.

int LibMC.MCAgency.SetDefaultAgentStatus

(

MCAgent.MC_AgentStatus_e

status

)

Sets the default state of an agent in the agency.

Can be used to set the default status of agents, but most agents managed their state on their own.

Parameters:

status

The enum that identifies the desired agent state.

Returns:

The return value of the underlying MC_SetDefaultAgentStatus function.

Definition at line 595 of file MCAgency.cs.

MCAgent LibMC.MCAgency.WaitRetrieveAgent

(

)

Waits for an agent to arrive and returns the agent.

Waits for an agent to arrive in the agency, then returns that agent. The agent is not allowed to execute.

Returns:

The agent that was retrieved or an empty agent if it fails.

Definition at line 608 of file MCAgency.cs.

int LibMC.MCAgency.WaitAgent

(

)

Waits for an agent to arrive.

Waits for an agent to arrive in the agency. The agent is allowed to execute normally.

Returns:

The return value of the underlying MC_WaitAgent function.

Definition at line 625 of file MCAgency.cs.

int LibMC.MCAgency.SendAgentMigrationMessageFile	(	String	filename,
		String	hostname,
		int	port
	)

Sends an agent migration message file to an agency.

Sends the specified XML file to another agency (local or remote).

Parameters:

	filename	The name of the file to send (fully qualified).
	hostname	The URL, IP address, or other identifier for the agency host.
	port	The port to send to.

Returns:

The return value of the underlying MC_SendAgentMigrationMessageFile function.

Definition at line 644 of file MCAgency.cs.

int LibMC.MCAgency.LoadAgentMigrationMessageFile

(

String

filename

)

Load an agent migration message.

Loads the specified XML file to this agency automatically. There is no need to specify a port or agency location.

Parameters:

filename

The name of the file to send (fully qualified).

Returns:

The return value of the underlying MC_SendAgentMigrationMessageFile function.

Definition at line 658 of file MCAgency.cs.

References LibMC.MCAgency.Port.

int LibMC.MCAgency.SendAgentMigrationMessage	(	String	message,
		String	hostname,
		int	port
	)

Sends an agent migration message to an agency.

Sends an agent migration message to another agency (local or remote).

Parameters:

	message	The agent migration message.
	hostname	The URL, IP address, or other identifier for the agency host.
	port	The port to send to.

Returns:

The return value of the underlying MC_SendAgentMigrationMessageFile function.

Definition at line 673 of file MCAgency.cs.

int LibMC.MCAgency.CondBroadcast

(

int

id

)

Broadcast a condition signal.

Broadcasts a signal in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit().

Parameters:

id

The ID number of the condition to signal.

Returns:

The return value of the underlying MC_CondBroadcast function.

Definition at line 691 of file MCAgency.cs.

int LibMC.MCAgency.CondSignal

(

int

id

)

Signal a condition.

Signals a condition in the agency. The parameter "id" is the ID of the agency sync variable to signal that was created with SyncInit().

Parameters:

id

The ID number of the condition to signal.

Returns:

The return value of the underlying MC_CondSignal function.

Definition at line 705 of file MCAgency.cs.

int LibMC.MCAgency.CondReset

(

int

id

)

Reset a condition signal.

Resets a signal in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit(). This function must be called after a condition is received in order to clear it.

Parameters:

id

The ID number of the condition to reset.

Returns:

The return value of the underlying MC_CondReset function.

Definition at line 720 of file MCAgency.cs.

int LibMC.MCAgency.CondWait

(

int

id

)

Wait for a condition signal.

Waits for a condition signal in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit(). This function blocks until the signal is received.

Parameters:

id

The ID number of the condition to wait for.

Returns:

The return value of the underlying MC_CondWait function.

Definition at line 735 of file MCAgency.cs.

int LibMC.MCAgency.MutexLock

(

int

id

)

Lock a mutex.

Locks a mutex in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit(). This function blocks until the mutex is locked.

Parameters:

id

The ID number of the mutex to lock.

Returns:

The return value of the underlying MC_MutexLock function.

Definition at line 750 of file MCAgency.cs.

int LibMC.MCAgency.MutexUnlock

(

int

id

)

Unlock a mutex.

Locks a mutex in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit().

Parameters:

id

The ID number of the mutex to unlock.

Returns:

The return value of the underlying MC_MutexUnlock function.

Definition at line 764 of file MCAgency.cs.

int LibMC.MCAgency.SemaphorePost

(

int

id

)

Posts a semaphore.

Posts a sempaphore in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit().

Parameters:

id

The ID number of the semaphore to post.

Returns:

The return value of the underlying MC_SemaphorePost function.

Definition at line 778 of file MCAgency.cs.

int LibMC.MCAgency.SemaphoreWait

(

int

id

)

Wait for a semaphore to be posted.

Wait for a semaphore in the agency to be posted. The parameter "id" is the ID of the agency sync variable created with SyncInit(). This function blocks until the semaphore is posted.

Parameters:

id

The ID number of the semaphore to wait for.

Returns:

The return value of the underlying MC_SemaphoreWait function.

Definition at line 793 of file MCAgency.cs.

int LibMC.MCAgency.ResetSignal

(

)

Reset an agency signal.

Resets a signal in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit().

Returns:

The return value of the underlying MC_ResetSignal function.

Definition at line 806 of file MCAgency.cs.

int LibMC.MCAgency.SyncDelete

(

int

id

)

Delete a synchronization variable.

Deletes a synchronization variable in the agency. The parameter "id" is the ID of the agency sync variable created with SyncInit().

Parameters:

id

The ID number of the variable to delete.

Returns:

The return value of the underlying MC_SyncDelete function.

Definition at line 820 of file MCAgency.cs.

int LibMC.MCAgency.SyncInit

(

int

id

)

Create a new synchronization variable.

Creates a new synchronization variable in the agency. The parameter "id" is desired ID of the variable. A random ID is returned if "id" is already in use.

Parameters:

id

The ID number of the condition to signal.

Returns:

The return value of the underlying MC_CondBroadcast function- either a random ID or the desired ID if the desired ID is already in use.

Definition at line 836 of file MCAgency.cs.

int LibMC.MCAgency.WaitSignal

(

int

signals

)

Wait for agency signals.

Waits for signals to occur in the agency.

Parameters:

signals

The ID number of the condition to signal.

Returns:

The return value of the underlying MC_WaitSignal function.

Definition at line 849 of file MCAgency.cs.

int LibMC.MCAgency.BarrierDelete

(

int

id

)

Delete a barrier object.

Deletes a barrier object from the agency. The parameter "id" is the ID of the agency sync variable created with BarrierInit().

Parameters:

id

The ID number of the barrier to delete.

Returns:

The return value of the underlying MC_BarrierDelete function.

Definition at line 863 of file MCAgency.cs.

int LibMC.MCAgency.BarrierInit	(	int	id,
		int	num_procs
	)

Create a new barrier.

Creates a new barrier object in the agency.

Parameters:

	id	The ID number of the condition to signal.
	num_procs	the number of process to block (?)

Returns:

The return value of the underlying MC_BarrierInit function.

Definition at line 877 of file MCAgency.cs.

MC_SteerCommand_e LibMC.MCAgency.SteerControl

(

)

Steering control function.

Really not sure.

Returns:

The return value of the underlying MC_SteerControl function.

Todo:

Test MC_SteerControl, MC_Steer.

Definition at line 895 of file MCAgency.cs.

int LibMC.MCAgency.Steer	(	IntPtr	funcptr,
		IntPtr	arg
	)

Steering control function.

Really not sure.

Parameters:

	funcptr	Pointer to the steering function
	arg	Argument to function

Returns:

The return value of the underlying _MC_Steer function.

Note:

This function does nothing but throw an exception right now.

Bug:

MC_Steer is not yet implemented.

Todo:

Implement MC_Steer

Definition at line 913 of file MCAgency.cs.

int LibMC.MCAgency.RegisterService	(	MCAgent	agent,
		int	agentID,
		String	agentName,
		String[]	serviceNames,
		int	numServices
	)

Registers services in the agency.

Registers services provided by agents with the agency. Not really useful in binary space.

Parameters:

	agent	The agent providing the services.
	agentID	The agent ID number.
	agentName	The agent name.
	serviceNames	An array of service names.
	numServices	The number of services provided.

Returns:

The return value of the underlying MC_RegisterService function.

Todo:

Test MC_RegisterService and MC_SearchForService.

Definition at line 938 of file MCAgency.cs.

References LibMC.MCAgent.Agent.

int LibMC.MCAgency.SearchForService	(	String	searchString,
		IntPtr	agentNames,
		IntPtr	serviceNames,
		IntPtr	agentIDs,
		IntPtr	numResults
	)

Searches for services in the agency.

Searches for services provided by agents with the agency. Not really useful in binary space.

Parameters:

	searchString	The agent providing the services.
	agentNames	The agent ID number.
	serviceNames	The agent name.
	agentIDs	An array of service names.
	numResults	The number of services provided.

Returns:

The return value of the underlying MC_SearchForService function.

Note:

This function does nothing but throw an exception right now.

Bug:

MC_SearchForService is not yet implemented.

Todo:

Implement SearchForService

Definition at line 961 of file MCAgency.cs.

int LibMC.MCAgency.AddAgent

(

MCAgent

agent

)

Add an agent to the agency.

Adds an agent to the agency.

Parameters:

agent

The agent to add.

Returns:

The return value of the underlying MC_AddAgent function.

Definition at line 979 of file MCAgency.cs.

References LibMC.MCAgent.Agent.

MCAgent LibMC.MCAgency.FindAgentByName

(

String

name

)

Finds an agent by its name.

Finds an agent in the agency by its name.

Parameters:

name

The name of the agent to search for.

Returns:

The return value of the underlying MC_FindAgentByName function.

Definition at line 992 of file MCAgency.cs.

MCAgent LibMC.MCAgency.FindAgentByID

(

int

id

)

Find an agent by its ID.

Finds an agent in the agency by its ID number.

Parameters:

id

The ID number of the condition to signal.

Returns:

The return value of the underlying MC_FindAgentByID function.

Definition at line 1005 of file MCAgency.cs.

MCAgent LibMC.MCAgency.RetrieveAgent

(

)

Retrieve an agent from the agency.

Really not sure.

Returns:

The return value of the underlying MC_CondBroadcast function.

Definition at line 1017 of file MCAgency.cs.

int LibMC.MCAgency.AclSend

(

MCAclMessage

acl_message

)

Send an ACL message to the agency.

Sends an ACL message to the agency. The message is delivered appropriately.

Parameters:

acl_message

The message to send.

Returns:

The return value of the underlying MC_CondBroadcast function.

Definition at line 1034 of file MCAgency.cs.

References LibMC.MCAclMessage.AclMsg.

int LibMC.MCAgency.MainLoop

(

)

Makes the agency wait indefinitely.

Makes the agency wait indefinitely until it receives a "quit" command or is otherwise terminated.

Returns:

The return value of the underlying MC_MainLoop function.

Definition at line 1047 of file MCAgency.cs.

---

Property Documentation

int LibMC.MCAgency.Port [get, set]

Accessor for the port number of the agency.

Allows the user to set the agency port or get the port number while it is running.

Note:

The port must be set before the agency is started. Once the agency is started, the port cannot be changed.

Definition at line 404 of file MCAgency.cs.

Referenced by LibMC.MCAgency.LoadAgentMigrationMessageFile().

MCAgencyState LibMC.MCAgency.State [get]

Accessor for the agency state.

Allows the user to query the state of the agency.

Note:

The state cannot be set by the user. It is controlled internally.

Definition at line 424 of file MCAgency.cs.

---

The documentation for this class was generated from the following files:

• /home/dko/projects/mobilec/trunk/src/win32/LibMC.net/LibMC/MCAgency.cs
• /home/dko/projects/mobilec/trunk/src/win32/LibMC.net/LibMC/MCExports.cs

---