Package ivy :: Module std_api
[hide private]
[frames] | no frames]

Source Code for Module ivy.std_api

  1  """ 
  2  Implements the standard Ivy API. 
  3   
  4  You can refer to the example code ``pyhello.py`` for an example of use. 
  5   
  6  All methods in this module are frontends to a `ivy.IvyServer` instance, stored 
  7  in the module's attributes `_IvyServer`. 
  8   
  9  :group Connecting to/disconnecting from the Ivy bus: 
 10    IvyInit, IvyStart,IvyMainLoop, IvyStop 
 11  :group Bindings: IvyBindMsg, IvyUnBindMsg, IvyBindDirectMsg 
 12  :group Inspecting the Ivy bus: 
 13    IvyGetApplicationList, IvyGetApplication, IvyGetApplicationName, 
 14    IvyGetApplicationHost 
 15  :group Interacting with other Ivy clients: 
 16    IvySendMsg, IvySendDieMsg, IvySendDirectMsg 
 17  :group Timers: IvyTimerRepeatAfter, IvyTimerModify, IvyTimerRemove 
 18   
 19  Copyright (c) 2005-2011 Sebastien Bigaret <sbigaret@users.sourceforge.net> 
 20  """ 
 21   
 22  _IvyServer=None 
 23   
 24  from ivy import IvyApplicationConnected, IvyApplicationDisconnected 
 25  from ivy import IvyRegexpAdded, IvyRegexpRemoved 
 26  from ivy import void_function 
 27   
28 -def IvyInit(agent_name, ready_msg=None, 29 main_loop_type_ignored=0, 30 on_cnx_fct=void_function, 31 on_die_fct=void_function):
32 """ 33 Initializes the module. This method should be called exactly once before any 34 other method is called. 35 """ 36 global _IvyServer 37 assert _IvyServer is None 38 from ivy import IvyServer 39 _IvyServer = IvyServer(agent_name, ready_msg, on_cnx_fct, on_die_fct)
40 41
42 -def IvyStart(ivybus=None):
43 """ 44 Starts the Ivy server and fully activate the client. Please refer to the 45 discussion in `IvyMainLoop()` 's documentation. 46 """ 47 assert _IvyServer != None 48 _IvyServer.start(ivybus)
49 50
51 -def IvyMainLoop():
52 """ 53 Simulates the original main loop: simply waits for the server termination. 54 55 Note that while the original API requires this to be called, this module 56 does NOT rely in any way on this method. In particular, a client is 57 fully functional and begins to receive messages as soon as the `IvyStart()` 58 method is called. 59 """ 60 assert _IvyServer != None 61 _IvyServer.server_termination.wait()
62 63
64 -def IvyStop():
65 assert _IvyServer != None 66 _IvyServer.stop()
67 68
69 -def IvyBindMsg(on_msg_fct, regexp):
70 """ 71 Registers a method that should be called each time a message matching 72 regexps is sent on the Ivy bus. 73 74 :return: an id identifying the binding, that can be used to unregister it 75 (see `IvyUnBindMsg()`) 76 """ 77 assert _IvyServer != None 78 return _IvyServer.bind_msg(on_msg_fct, regexp)
79
80 -def IvyBindDirectMsg(on_msg_fct):
81 """ 82 Registers a method that should be called each time someone sends us 83 a direct message 84 85 """ 86 assert _IvyServer != None 87 return _IvyServer.bind_direct_msg(on_msg_fct)
88
89 -def IvyUnBindMsg(id):
90 """ 91 Unregisters a binding 92 93 :param id: the binding's id, as previously returned by `IvyBindMsg()`. 94 :return: the regexp corresponding to the unsubscribed binding 95 :except KeyError: if no such subscription can be found 96 """ 97 assert _IvyServer != None 98 return _IvyServer.unbind_msg(id)
99
100 -def IvyBindRegexpChange(regexp_change_callback):
101 """ 102 """ 103 assert _IvyServer != None 104 return _IvyServer.bind_regexp_change(regexp_change_callback)
105
106 -def IvySendMsg(msg):
107 """ 108 Sends a message on the bus 109 """ 110 assert _IvyServer != None 111 return _IvyServer.send_msg(msg)
112
113 -def IvySendDieMsg(client):
114 """ 115 Sends a "die" message to `client`, instructing him to terminate. 116 117 :param client: an `ivy.IvyClient` object, as returned by 118 `IvyGetApplication()` 119 """ 120 assert _IvyServer != None 121 client.send_die_message()
122 123
124 -def IvySendDirectMsg(client, num_id, msg):
125 """ 126 Sends a message directly to an other Ivy client, with the supplied 127 numerical id and message. 128 129 :Parameters: 130 - `client`: an `ivy.IvyClient` object, as returned by 131 `IvyGetApplication()` 132 - `num_id`: an additional integer to use. It may, or may not, be 133 meaningful, this only depends on the usage your application makes of 134 it, the Ivy protocol itself does not care and simply transmits it 135 along with the message. 136 - `msg`: the message to send 137 """ 138 assert _IvyServer != None 139 client.send_direct_message(num_id, msg)
140 141
142 -def IvySendError(client, num_id, error_msg):
143 """ 144 Sends an "error" message to `client` 145 146 :Parameters: 147 - `client`: an `ivy.IvyClient` object, as returned by 148 `IvyGetApplication()` 149 - `num_id`: an additional integer to use. It may, or may not, be 150 meaningful, this only depends on the usage your application makes of 151 it, the Ivy protocol itself does not care and simply transmits it 152 along with the message. 153 - `error_msg`: the message to send 154 """ 155 assert _IvyServer != None 156 client.send_error(num_id, error_msg)
157 158
159 -def IvyGetApplicationList():
160 """ 161 Returns the names of the applications that are currently connected 162 """ 163 assert _IvyServer != None 164 return _IvyServer.get_clients()
165
166 -def IvyGetApplicationMessages(client):
167 """ 168 Returns all subscriptions for that client 169 170 :param client: an `ivy.IvyClient` object, as returned by 171 `IvyGetApplication()` 172 :return: list of tuples (idx, regexp) 173 """ 174 return client.get_regexps()
175
176 -def IvyGetApplication(name):
177 """ 178 Returns the Ivy client registered on the bus under the given name. 179 180 .. warning:: if multiple applications are registered w/ the same name only 181 one is returned 182 183 :returns: an `ivy.IvyClient` object 184 """ 185 assert _IvyServer != None 186 clients = _IvyServer.get_client_with_name(name) 187 return clients and clients[0] or None
188
189 -def IvyGetApplicationName(client):
190 """ 191 Equivalent to ``client.agent_name`` 192 193 :param client: an `ivy.IvyClient` object, as returned by 194 `IvyGetApplication()` 195 """ 196 return client.agent_name
197
198 -def IvyGetApplicationHost(client):
199 """ 200 Equivalent to ``client.fqdn``. IP address is stored under ``client.ip``, 201 and port number under ``client.port`` 202 203 :param client: an `ivy.IvyClient` object, as returned by 204 `IvyGetApplication()` 205 """ 206 return client.fqdn
207 208 209 _timers={}
210 -def IvyTimerRepeatAfter(count, delay, callback):
211 """ 212 Creates and activates a new timer 213 214 :Parameters: 215 - `count`: nb of time to repeat the loop, ``0`` (zero) for an endless loop 216 - `delay`: the delay between ticks, in milliseconds 217 - `callback`: the function to call on every tick. That function is 218 called without any parameters. 219 220 :return: the timer's id 221 """ 222 assert _IvyServer != None 223 from ivy import IvyTimer 224 # The original python API relies on a callback called without any parameter 225 cb = lambda timer, callback=callback: callback() 226 timer = IvyTimer(_IvyServer, count, delay, cb) 227 _timers[timer.id]=timer 228 timer.start() 229 return timer.id
230 231
232 -def IvyTimerModify(timer_id, delay):
233 """ 234 Modifies a timer's delay. Note that the modification will happen after 235 the next tick. 236 237 :Parameters: 238 - `timer_id`: id of the timer to modify, as returned by 239 `IvyTimerRepeatAfter()` 240 - `delay`: the delay, in milliseconds, between ticks 241 """ 242 _timers[timer_id].delay = delay
243 244
245 -def IvyTimerRemove(timer_id):
246 """ 247 Stops and removes a given timer. 248 249 :param timer_id: id of the timer, as returned by `IvyTimerRepeatAfter` 250 """ 251 from ivy import IvyTimer 252 timer = _timers[timer_id] 253 timer.abort = True 254 del _timers[timer_id]
255 256 257 258 #TODO IvyUnBindMsg(id) 259 260 261 """ 262 # copy/paste for quick tests w/ ivyprobe 263 from ivy.std_api import * 264 IvyInit('Test', 'test welcome', 0) 265 IvyStart() 266 def onmsgproc(*larg): 267 print larg 268 269 IvyBindMsg(onmsgproc, '(.*)') 270 IvyGetApplicationList() 271 app=IvyGetApplication('IVYPROBE') 272 IvyGetApplicationName(app) 273 IvyGetApplicationHost(app) 274 IvySendDirectMsg(app, 765, 'glop') 275 IvySendDieMsg(app) 276 """ 277