Package ivy :: Module ivy :: Class IvyClient
[hide private]
[frames] | no frames]

Class IvyClient

source code

Represents a client connected to the bus. Every callback methods registered by an agent receive an object of this type as their first parameter, so that they know which agent on the bus is the cause of the event which triggered the callback.

An IvyClient is responsible for:

It is not responsible for receiving messages from the client: another object is in charge of that, namely an IvyHandler object.

The local IvyServer creates one IvyClient per agent on the bus.

MT-safety

See the discussion in regexps.

Instance Methods [hide private]
 
__init__(self, ip, port, client_socket, agent_id=None, agent_name=None) source code
 
get_regexps(self) source code
 
send_error(self, num_id, msg)
Sends an error message
source code
 
__eq__(self, client)
cf.
source code
 
__hash__(self)
hash((self.ip, self.port))
source code
 
__repr__(self)
Returns 'ip:port (agent_name)'
source code
 
__str__(self)
Returns 'agent_name@FQDN'
source code
 
_send(self, msg_type, *params)
Internally used to send message to the remote agent through the opened socket self.socket.
source code
    Protocol-related methods
 
start_init(self, agent_name)
Finalizes the initialization process by setting the client's agent_name.
source code
 
end_init(self)
Should be called when the initalization process ends.
source code
 
send_new_subscription(self, idx, regexp)
Notifies the remote agent that we (the local agent) subscribe to a new type of messages
source code
 
remove_subscription(self, idx)
Notifies the remote agent that we (the local agent) are not interested in a given subscription.
source code
 
wave_bye(self, id=0)
Notifies the remote agent that we are about to quit
source code
    Manipulating the remote agent's subscriptions
 
add_regexp(self, regexp_id, regexp) source code
 
remove_regexp(self, regexp_id)
Removes a regexp
source code
    Sending messages
 
send_msg(self, msg)
Sends a message to the client.
source code
 
send_direct_message(self, num_id, msg)
Sends a direct message
source code
 
send_die_message(self, num_id=0, msg='')
Sends a die message
source code
Class Variables [hide private]
  agent_id = None
  agent_name = None
  port = None
  socket = None
Instance Variables [hide private]
threading.Lock regexp_lock
a non-reentrant lock protecting the variable regexps.
  regexps
a dictionary mapping subscriptions' ids (as delivered by add_regexp) to the corresponding regular expressions.
Method Details [hide private]

start_init(self, agent_name)

source code 
Finalizes the initialization process by setting the client's agent_name. This is a Ivy protocol requirement that an application sends its agent-name only once during the initial handshake (beginning with message of type START_INIT and ending with a type END_INIT). After this method is called, we expect to receive the initial subscriptions for that client (or none); the initialization process completes after end_init is called.
Raises:

end_init(self)

source code 
Should be called when the initalization process ends.
Raises:
  • IvyIllegalStateError - if the method has already been called (and self.status has already been set to INITIALIZED)

add_regexp(self, regexp_id, regexp)

source code 
Raises:

remove_regexp(self, regexp_id)

source code 
Removes a regexp
Returns:
the regexp that has been removed
Raises:

send_msg(self, msg)

source code 
Sends a message to the client. The message is compared to the client's subscriptions and it is sent if one of them matches.
Returns:
True if the message was actually sent to the client, that is: if there is a regexp matching the message in the client's subscriptions; returns False otherwise.

send_direct_message(self, num_id, msg)

source code 

Sends a direct message

Note: the message will be encoded by encode_message with numerical_id=num_id and params==msg; this means that if msg is not a string but a list or a tuple, the direct message will contain more than one parameter. This is an extension of the original Ivy design, supported by python, but if you want to inter-operate with applications using the standard Ivy API the message you send must be a string. See in particular in ivy.h:

typedef void (*MsgDirectCallback)( IvyClientPtr app, void *user_data, int id, char *msg ) ;

send_new_subscription(self, idx, regexp)

source code 
Notifies the remote agent that we (the local agent) subscribe to a new type of messages
Parameters:
  • idx - : the index/id of the new subscription. It is the responsability of the local agent to make sure that every subscription gets a unique id.
  • regexp - : a regular expression. The subscription consists in receiving messages mathcing the regexp.

remove_subscription(self, idx)

source code 
Notifies the remote agent that we (the local agent) are not interested in a given subscription.
Parameters:

__eq__(self, client)
(Equality operator)

source code 
cf. dict[client] or dict[(ip,port)] UNNEEDED FOR THE MOMENT

_send(self, msg_type, *params)

source code 

Internally used to send message to the remote agent through the opened socket self.socket. This method catches all exceptions socket.error and socket.timeout and ignores them, simply logging them at the "info" level.

The errors that can occur are for example:

socket.timeout: timed out
socket.error: (104, 'Connection reset by peer')
socket.error: (32, 'Broken pipe')

They can happen after a client disconnects abruptly (because it was killed, because the network is down, etc.). We assume here that if and when an error happens here, a disconnection will be detected shortly afterwards by the server which then removes this agent from the bus. Hence, we ognore the error; please also note that not ignoring the error can have an impact on code, for example, IyServer.send_msg() does not expect that IvyClient.send() fails and if it fails, it is possible that the server does not send the message to all possible subscribers.

Note:

ivysocket.c:SocketSendRaw() also ignores error, simply logging them.


Instance Variable Details [hide private]

regexp_lock

a non-reentrant lock protecting the variable regexps. Used by methods add_regexp, remove_regexp and send_msg.
Type:
threading.Lock

regexps

a dictionary mapping subscriptions' ids (as delivered by add_regexp) to the corresponding regular expressions. Precisely, it maps ids to tuples being (regexp_as_string, compiled_regexp). You shouldn't directly access or manipulate this variable, use add_regexp and remove_regexp instead; however if you really need/want to, you must acquire the regexp_lock before accessing/modifying it.