Mobile-C: /home/dko/projects/mobilec/trunk/src/include/libmc.h Source File

00001 /* SVN FILE INFO
00002  * $Revision: 174 $ : Last Committed Revision
00003  * $Date: 2008-06-24 10:50:29 -0700 (Tue, 24 Jun 2008) $ : Last Committed Date */
00004 /*[
00005  * Copyright (c) 2007 Integration Engineering Laboratory
00006                       University of California, Davis
00007  *
00008  * Permission to use, copy, and distribute this software and its
00009  * documentation for any purpose with or without fee is hereby granted,
00010  * provided that the above copyright notice appear in all copies and
00011  * that both that copyright notice and this permission notice appear
00012  * in supporting documentation.
00013  *
00014  * Permission to modify the software is granted, but not the right to
00015  * distribute the complete modified source code.  Modifications are to
00016  * be distributed as patches to the released version.  Permission to
00017  * distribute binaries produced by compiling modified sources is granted,
00018  * provided you
00019  *   1. distribute the corresponding source modifications from the
00020  *    released version in the form of a patch file along with the binaries,
00021  *   2. add special version identification to distinguish your version
00022  *    in addition to the base release version number,
00023  *   3. provide your name and address as the primary contact for the
00024  *    support of your modified version, and
00025  *   4. retain our contact information in regard to use of the base
00026  *    software.
00027  * Permission to distribute the released version of the source code along
00028  * with corresponding source modifications in the form of a patch file is
00029  * granted with same provisions 2 through 4 for binary distributions.
00030  *
00031  * This software is provided "as is" without express or implied warranty
00032  * to the extent permitted by applicable law.
00033 ]*/
00034 
00052 /* Filename: libmc.h */
00053 /* Current functions implemented 
00054 MC_AclDestroy
00055 MC_AclNew
00056 MC_AclPost
00057 MC_AclReply
00058 MC_AclRetrieve
00059 MC_AclSend
00060 MC_AclWaitRetrieve
00061 MC_AddAgent 
00062 MC_Barrier 
00063 MC_BarrierInit 
00064 MC_BarrierDelete 
00065 MC_CallAgentFunc
00066 MC_ChInitializeOptions 
00067 MC_ComposeAgent
00068 MC_CondBroadcast 
00069 MC_CondSignal 
00070 MC_CondWait  
00071 MC_CondReset 
00072 MC_CopyAgent 
00073 MC_DeleteAgent 
00074 MC_DeregisterService
00075 MC_End 
00076 MC_FindAgentByName
00077 MC_FindAgentByID
00078 MC_GetAgentArrivalTime 
00079 MC_GetAgentStatus 
00080 MC_GetAgentXMLString 
00081 MC_GetAgentExecEngine 
00082 MC_GetAgentID
00083 MC_GetAgentName
00084 MC_GetAgentReturnData
00085 MC_GetAgentNumTasks 
00086 MC_GetAgentType 
00087 MC_GetAllAgents 
00088 MC_HaltAgency 
00089 MC_Initialize
00090 MC_InitializeAgencyOptions 
00091 MC_MutexLock 
00092 MC_MutexUnlock 
00093 MC_PrintAgentCode 
00094 MC_RegisterService
00095 MC_ResumeAgency 
00096 MC_RetrieveAgent 
00097 MC_RetrieveAgentCode 
00098 MC_ResetSignal 
00099 MC_SearchForService
00100 MC_SemaphorePost 
00101 MC_SemaphoreWait 
00102 MC_SendCh
00103 MC_SendAgentMigrationMessage
00104 MC_SendAgentMigrationMessageFile
00105 MC_SendSteerCommand 
00106 MC_SetAgentStatus 
00107 MC_SetDefaultAgentStatus
00108 MC_SetThreadOn 
00109 MC_SetThreadsAllOn
00110 MC_SetThreadOff 
00111 MC_SetThreadsAllOff
00112 MC_Steer
00113 MC_SteerControl 
00114 MC_SyncDelete 
00115 MC_SyncInit 
00116 MC_TerminateAgent 
00117 MC_MainLoop 
00118 MC_MainLoop
00119 MC_WaitAgent 
00120 MC_WaitRetrieveAgent 
00121 MC_WaitSignal 
00122 
00123    *** */
00124 
00125 #ifndef _MOBILEC_H_
00126 #define _MOBILEC_H_
00127 
00128 #ifdef WIN32
00129         #ifdef _MC_DLL
00130                 // Building a .dll - export functions as marked
00131                 #define EXPORTMC _declspec(dllexport)
00132         #else
00133                 // Not building a .dll - building .lib assumed - no export required
00134                 #define EXPORTMC
00135         #endif
00136 #else
00137         // Not windows
00138         #define EXPORTMC
00139 #endif
00140 
00141 /* The MC_Wait() function is deprecated as of version 1.9.4.
00142  * All calls to MC_Wait() should now be changed to MC_MainLoop() */
00143 #define MC_Wait(arg1) \
00144   MC_MainLoop(arg1)
00145 
00146 #include <embedch.h>
00147 #ifdef __cplusplus
00148 extern "C" {
00149 #endif
00150 
00151 #ifndef _ERROR_CODE_E_
00152 #define _ERROR_CODE_E_
00153 /*
00154  * Error Codes
00155  * NOTE: There is a copy of this enum in mc_error.h
00156  * */
00157 typedef enum error_code_e {
00158     MC_SUCCESS = 0,
00159     MC_ERR,
00160     MC_ERR_CONNECT,
00161     MC_ERR_PARSE,
00162     MC_ERR_EMPTY,
00163     MC_ERR_INVALID,
00164     MC_ERR_INVALID_ARGS,
00165     MC_ERR_NOT_FOUND,
00166     MC_ERR_MEMORY,
00167     MC_ERR_SEND,
00168     MC_WARN_DUPLICATE
00169 } error_code_t;
00170 #endif
00171 
00175 enum MC_ThreadIndex_e{ 
00176     MC_THREAD_DF=0,   
00177     MC_THREAD_AMS,    
00178     MC_THREAD_ACC,    
00179     MC_THREAD_CP,     
00180     MC_THREAD_AGENT,  
00181     MC_THREAD_ALL };
00182 
00183 
00187 typedef enum MC_SteerCommand_e {
00188   MC_RUN = 0,     
00189   MC_SUSPEND,     
00190   MC_RESTART,     
00191   MC_STOP         
00192 } MC_SteerCommand_t;
00193 
00202 enum MC_Signal_e{
00203     MC_NO_SIGNAL      =0x00, 
00204     MC_RECV_CONNECTION=0x01, 
00205     MC_RECV_MESSAGE   =0x02, 
00206     MC_RECV_AGENT     =0x04, 
00207     MC_RECV_RETURN    =0x08, 
00208     MC_EXEC_AGENT     =0x0F, 
00209     MC_ALL_SIGNALS    =0x10  
00210 };
00211 
00215 typedef struct agency_s {
00216     int client;
00217     int server;
00218     char *hostName;                     
00219     char *filename;
00220     int portno;                         
00221     int portnoc;
00222     struct mc_platform_s* mc_platform;  
00223     int default_agentstatus;            
00224     int threads;                        
00225     int enable_security;                
00226     int stack_size[MC_THREAD_ALL];
00227     error_code_t last_error;
00228 } agency_t;
00229 typedef agency_t* agency_p;
00230 typedef agency_p MCAgency_t;
00231 
00235 typedef struct MCAgencyOptions_s{
00236     int threads;              
00237     int default_agent_status; 
00238     int modified;             
00239     int enable_security;      
00241     /* Following are some thread stack size options: unix/pthreads only! */
00242     int stack_size[MC_THREAD_ALL]; 
00243 } MCAgencyOptions_t;
00244 
00245 #ifndef AGENT_T
00246 #define AGENT_T
00247 typedef struct agent_s agent_t;
00248 typedef agent_t* MCAgent_t;
00249 typedef agent_t* agent_p;
00250 #endif
00251 
00252 enum MC_AgentType_e{ MC_NONE = -1, MC_REMOTE_AGENT = 0, MC_LOCAL_AGENT, MC_RETURN_AGENT };
00253 
00257 enum MC_AgentStatus_e{ 
00258         MC_NO_STATUS = -1,
00259     MC_WAIT_CH = 0,    
00260     MC_WAIT_MESSGSEND, 
00261     MC_AGENT_ACTIVE,   
00262     MC_AGENT_NEUTRAL,  
00263     MC_AGENT_SUSPENDED,
00264     MC_WAIT_FINISHED   
00265 };
00266 
00267 struct fipa_acl_message_s;
00268 
00276 EXPORTMC int 
00277 MC_AclDestroy(struct fipa_acl_message_s* message);
00278 
00284 EXPORTMC extern struct fipa_acl_message_s*
00285 MC_AclNew(void);
00286 
00295 EXPORTMC extern int MC_AclPost(MCAgent_t agent, struct fipa_acl_message_s* message);
00296 
00307 EXPORTMC extern struct fipa_acl_message_s*
00308 MC_AclReply(struct fipa_acl_message_s* acl_message);
00309 
00317 EXPORTMC extern struct fipa_acl_message_s* MC_AclRetrieve(MCAgent_t agent);
00318 
00327 EXPORTMC extern int MC_AclSend(MCAgency_t attr, struct fipa_acl_message_s* acl);
00328 
00336 EXPORTMC extern struct fipa_acl_message_s* MC_AclWaitRetrieve(MCAgent_t agent);
00337 
00338 /* ACL Helper Functions Here */
00339 enum fipa_performative_e;
00340 
00341 EXPORTMC int MC_AclSetPerformative(
00342     struct fipa_acl_message_s* acl,
00343     enum fipa_performative_e performative );
00344 
00345 EXPORTMC int MC_AclSetSender(
00346     struct fipa_acl_message_s* acl,
00347     const char* name,
00348     const char* address );
00349   
00350 EXPORTMC int MC_AclAddReceiver(
00351     struct fipa_acl_message_s* acl,
00352     const char* name,
00353     const char* address );
00354 
00355 EXPORTMC int MC_AclAddReplyTo(
00356     struct fipa_acl_message_s* acl,
00357     const char* name,
00358     const char* address);
00359 
00360 EXPORTMC int MC_AclSetContent(
00361     struct fipa_acl_message_s* acl,
00362     const char* content );
00363 
00364 /* End ACL Helper Functions */
00365 
00366 
00375 EXPORTMC extern int MC_AddAgent( 
00376     MCAgency_t attr, 
00377     MCAgent_t agent);
00378 
00394 extern const void* 
00395 MC_AgentVariableRetrieve(
00396     MCAgent_t agent,
00397     const char* var_name,
00398     int task_num);
00399 
00417 extern int 
00418 MC_AgentVariableSave(MCAgent_t agent, const char* var_name);
00419 
00429 EXPORTMC extern int MC_BarrierDelete(MCAgency_t attr, int id);
00430 
00446 EXPORTMC extern int MC_BarrierInit(MCAgency_t attr, int id, int num_procs);
00447 
00456 EXPORTMC extern int MC_ChInitializeOptions(MCAgency_t attr, ChOptions_t *options);
00457 
00474 EXPORTMC extern int MC_CallAgentFunc(
00475         MCAgent_t agent,
00476         const char* funcName,
00477         void* returnVal,
00478         void* varg
00479         );
00480 
00481 
00495 MCAgent_t
00496 MC_ComposeAgent(
00497     const char* name,
00498     const char* home,
00499     const char* owner, 
00500     const char* code,
00501     const char* return_var_name,
00502     const char* server,
00503     int persistent
00504     );
00505 
00516 EXPORTMC extern int MC_CondBroadcast(MCAgency_t attr, int id);
00517 
00533 EXPORTMC extern int MC_CondSignal(MCAgency_t attr, int id);
00534 
00545 EXPORTMC extern int MC_CondReset(MCAgency_t attr, int id);
00546 
00560 EXPORTMC extern int MC_CondWait(MCAgency_t attr, int id);
00561 
00571 int MC_CopyAgent(MCAgent_t* agent_out, const MCAgent_t agent_in);
00572 
00581 EXPORTMC extern int MC_DeleteAgent(MCAgent_t agent);
00582 
00593 EXPORTMC extern int MC_End(MCAgency_t attr);
00594 
00605 int MC_DestroyServiceSearchResult(
00606     char** agentName,
00607     char** serviceName,
00608     int* agentID,
00609     int numResult);
00610 
00611 
00622 EXPORTMC extern MCAgent_t MC_FindAgentByName(MCAgency_t attr, const char *name);
00623 
00632 EXPORTMC extern MCAgent_t MC_FindAgentByID(MCAgency_t attr, int ID);
00633 
00642 EXPORTMC extern /*ChInterp_t*/ void* MC_GetAgentExecEngine(MCAgent_t agent);
00643 
00647 EXPORTMC extern int MC_GetAgentID(MCAgent_t agent);
00648 
00649 /*
00650  * \brief           Retrieve an agent's name
00651  *
00652  * \return          a malloc'd character string on success, or NULL on failure
00653  */
00654 EXPORTMC extern char* MC_GetAgentName(MCAgent_t agent);
00655 
00661 EXPORTMC extern int MC_GetAgentNumTasks(MCAgent_t agent);
00662 
00679 EXPORTMC extern int MC_GetAgentReturnData(
00680         MCAgent_t agent,
00681         int task_num,
00682         void **data,
00683         int *dim,
00684         int **extent);
00685 
00691 EXPORTMC extern int MC_GetAgentStatus(MCAgent_t agent);
00692 
00698 EXPORTMC extern enum MC_AgentType_e MC_GetAgentType(MCAgent_t agent);
00699 
00705 EXPORTMC extern char* MC_GetAgentXMLString(MCAgent_t agent);
00706 
00714 EXPORTMC extern int MC_HaltAgency(MCAgency_t agency);
00715 
00726 EXPORTMC extern MCAgency_t MC_Initialize(
00727         int port,
00728         MCAgencyOptions_t *options);
00729 
00742 EXPORTMC extern int MC_InitializeAgencyOptions(struct MCAgencyOptions_s* options);
00743 
00749  EXPORTMC extern int MC_MainLoop(MCAgency_t attr);
00750 
00759 EXPORTMC extern int MC_LoadAgentFromFile(MCAgency_t attr, const char* filename);
00760 
00775 EXPORTMC extern int MC_MutexLock(MCAgency_t attr, int id); 
00776 
00777 /*
00778  * \brief           Unlocks a MobileC synchronization variable
00779  *
00780  * \param attr      a MobileC agency handle
00781  * \param id        the synchronization variable id to unlock
00782  *
00783  * \return          0 on success, error_code_t type on failure
00784  *
00785  * \see             MC_MutexLock()
00786  */
00787 EXPORTMC extern int MC_MutexUnlock(MCAgency_t attr, int id); 
00788 
00806 EXPORTMC extern int MC_RegisterService(
00807         MCAgency_t agency,
00808         /* Optional input args: Must input 
00809          * MCAgent_t OR
00810          * agentID AND agentName */
00811         MCAgent_t agent,
00812         int agentID,
00813         const char *agentName,
00814         char **serviceNames,
00815         int numServices);
00816 
00824 EXPORTMC extern int MC_ResumeAgency(MCAgency_t agency);
00825 
00831 EXPORTMC extern MCAgent_t MC_RetrieveAgent(MCAgency_t attr);
00832 
00844 EXPORTMC extern int MC_SemaphorePost(MCAgency_t attr, int id);
00845 
00859 EXPORTMC extern int MC_SemaphoreWait(MCAgency_t attr, int id);
00860 
00872 EXPORTMC extern int MC_SetDefaultAgentStatus(MCAgency_t agency, enum MC_AgentStatus_e status);
00873 
00887 EXPORTMC extern int MC_SetThreadOn(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index);
00888 
00897 EXPORTMC extern int MC_SetThreadsAllOn(MCAgencyOptions_t* options);
00898 
00912 EXPORTMC extern int MC_SetThreadOff(MCAgencyOptions_t *options, enum MC_ThreadIndex_e index );
00913 
00922 EXPORTMC extern int MC_SetThreadsAllOff(MCAgencyOptions_t* options);
00923 
00929 EXPORTMC extern int MC_PrintAgentCode(MCAgent_t agent);
00930 
00936 EXPORTMC extern char * MC_RetrieveAgentCode(MCAgent_t agent);
00937 
00945 EXPORTMC extern int MC_ResetSignal(MCAgency_t attr);
00946 
00962 EXPORTMC extern int MC_SearchForService(
00963         /* Input args */
00964         MCAgency_t attr, 
00965         const char *searchString,
00966         /* Return Args */
00967         char*** agentNames,
00968         char*** serviceNames,
00969         int** agentIDs,
00970         int* numResults);
00971 
00980 EXPORTMC extern int MC_SendAgentMigrationMessage(MCAgency_t attr,
00981         const char *message,
00982         const char *hostname,
00983         int port);
00984 
00993 EXPORTMC extern int MC_SendAgentMigrationMessageFile(MCAgency_t attr, 
00994         const char *filename,
00995         const char *hostname,
00996         int port);
00997 
01006 EXPORTMC extern int MC_SetAgentStatus(MCAgent_t agent, int status);
01007 
01023 EXPORTMC extern int MC_Steer( MCAgency_t attr, int (*funcptr)(void* data), void *arg);
01024 
01033 EXPORTMC extern enum MC_SteerCommand_e MC_SteerControl(void);
01034 
01043 EXPORTMC extern int MC_SyncDelete(MCAgency_t attr, int id);
01044 
01060 EXPORTMC extern int MC_SyncInit(MCAgency_t attr, int id);
01061 
01067 EXPORTMC extern int MC_TerminateAgent(MCAgent_t agent);
01068 
01074 /* EXPORTMC extern int MC_Wait(MCAgency_t attr); */
01075 
01082 EXPORTMC extern int MC_WaitAgent(MCAgency_t attr);
01083 
01092 EXPORTMC extern MCAgent_t MC_WaitRetrieveAgent(MCAgency_t attr);
01093 
01107 EXPORTMC extern int MC_WaitSignal(MCAgency_t attr, int signals);
01108 
01109 #ifdef __cplusplus
01110 }
01111 #endif
01112 
01113 #endif /* _MOBILEC_H_ */
01114