LibMC.NET: LibMC.MCAgency Class Reference

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...
enum	MC_Signal_e
	MobileC system signals. 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

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.

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 349 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 363 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.

enum LibMC::MCAgency::MC_Signal_e

MobileC system signals.

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

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

See also:: MC_WaitSignal(), MC_ResetSignal()

Definition at line 111 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 381 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 459 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 481 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 499 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 530 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 546 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 561 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 576 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 593 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 609 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 622 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 639 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 658 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 672 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 687 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:

The ID number of the condition to signal.

Returns:: The return value of the underlying MC_CondBroadcast function.

Definition at line 705 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:

The ID number of the condition to signal.

Returns:: The return value of the underlying MC_CondSignal function.

Definition at line 719 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:

The ID number of the condition to reset.

Returns:: The return value of the underlying MC_CondReset function.

Definition at line 734 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:

The ID number of the condition to wait for.

Returns:: The return value of the underlying MC_CondWait function.

Definition at line 749 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:

The ID number of the mutex to lock.

Returns:: The return value of the underlying MC_MutexLock function.

Definition at line 764 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:

The ID number of the mutex to unlock.

Returns:: The return value of the underlying MC_MutexUnlock function.

Definition at line 778 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:

The ID number of the semaphore to post.

Returns:: The return value of the underlying MC_SemaphorePost function.

Definition at line 792 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:

The ID number of the semaphore to wait for.

Returns:: The return value of the underlying MC_SemaphoreWait function.

Definition at line 807 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 820 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:

The ID number of the variable to delete.

Returns:: The return value of the underlying MC_SyncDelete function.

Definition at line 834 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:

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 850 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 863 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:

The ID number of the barrier to delete.

Returns:: The return value of the underlying MC_BarrierDelete function.

Definition at line 877 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 891 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 909 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 927 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 952 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 975 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 993 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 1006 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:

The ID number of the condition to signal.

Returns:: The return value of the underlying MC_FindAgentByID function.

Definition at line 1019 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 1031 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 1048 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 1061 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 418 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 438 of file MCAgency.cs.

LibMC.MCAgency Class Reference

Public Types

Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation