#include <dht/client.h>
Inheritance diagram for dht::client:
Public Types | |
| enum | { disconnected = 1, connecting, connected, disconnecting } |
Public Member Functions | |
| virtual | ~client () |
| Destructor. | |
| virtual int | in_state () const |
| Returns the state of client (disconnected, connecting etc.). | |
| virtual const char * | in_state_str () const |
| Returns the current state of client as a string. | |
| virtual const char * | state_str (int state) const |
| Returns the client state as a string. | |
| virtual void | init (const dht::name_value_map &opts)=0 |
| Optional initialization for the implementation. | |
| virtual void | observer_attach (dht::event_observer *h, int event_mask) |
| Adds observer. | |
| virtual void | observer_remove (dht::event_observer *h) |
| Removes observer. | |
| virtual void | observer_remove (dht::event_observer *h, int event_mask) |
| Removes observer. | |
| virtual void | connect (dht::notify_handler *handler=NULL)=0 |
| Connects client to DHT. | |
| virtual void | disconnect (dht::notify_handler *handler=NULL)=0 |
| Disconnects client from DHT. | |
| virtual void | find (const dht::key &fkey, dht::search_handler *handler)=0 |
| Searches the DHT for value matching the given key. | |
| virtual void | store (const dht::key &skey, const dht::value &svalue, dht::notify_handler *handler=NULL)=0 |
| Stores a value to DHT. | |
| virtual const addr_inet_type & | external_addr ()=0 |
| Gets client's external address. | |
| virtual int | process (time_value_type &max_wait)=0 |
| Does DHT specific processing. | |
| virtual int | process (time_value_type *max_wait=NULL)=0 |
| Does DHT specific processing. | |
| virtual reactor_type * | reactor ()=0 |
| Returns the reactor which is used for event demultiplexing. | |
| virtual void | reactor (reactor_type *reactor)=0 |
| Sets the reactor which is used for event demultiplexing. | |
| virtual int | handler_cancel (dht::notify_handler *handler)=0 |
| cancels a handler | |
Protected Member Functions | |
| event_observer_notifier * | observer_notifier () |
The interface does not need to be thread safe. If the functions in the class are called from several threads the application must manage the synchronization so that several functions are not called at once. Likewise, if the implementation of the interface internally uses threads it must make sure all handlers are called only from the thread that called process() function.
The most convenient way to obtain results is by adding observers for different events, such as change of state (from connecting to connected), search results etc. Several of the functions can also receive pointer to handler that will be called when the operation is finished. The handler will only be called while being in process() and from the same thread that called process(). This rule must be obeyed by implementations even in the case when the call's success/failure status could be directly determined when calling the function.
Generally all heavy weight processing must happen in process() functions. The other functions, such as connect(), find(), store() and disconnect() should delay processing that requires waiting, for example network operations to finish, to when user calls one of the process() functions. The calling application should for the most time be calling process() functions and react when observers or handler objects are notified of new events.
The functions are allowed to throw exceptions in case of errors. Exceptions should be reserved for serious usage/operational errors, such as calling store() without being connected, or running out of memory. If the function that received a handler throws exception, the handler's success/failure function will not be called. In other error events, such as timeout of connecting, the specified handler if any should be called with failure status.
In general the typical usage sequence of the interface is the following:
| virtual dht::client::~client | ( | ) | [virtual] |
Destructor.
When destructor called the implementation should clean up as quickly as possible. If any handlers are pending they do not need to be called. For clean shutdown disconnect() should be called first (if connect() has been called)
Reimplemented in dht::kadc::client.
| virtual int dht::client::in_state | ( | ) | const [virtual] |
Returns the state of client (disconnected, connecting etc.).
| virtual const char* dht::client::in_state_str | ( | ) | const [virtual] |
Returns the current state of client as a string.
| virtual const char* dht::client::state_str | ( | int | state | ) | const [virtual] |
| virtual void dht::client::init | ( | const dht::name_value_map & | opts | ) | [pure virtual] |
Optional initialization for the implementation.
| opts | name/value pairs of options, implementation specific |
Implemented in dht::kadc::client.
| virtual void dht::client::observer_attach | ( | dht::event_observer * | h, | |
| int | event_mask | |||
| ) | [virtual] |
Adds observer.
| h | observer | |
| event_mask | events that will cause observer to be notified |
| virtual void dht::client::observer_remove | ( | dht::event_observer * | h | ) | [virtual] |
Removes observer.
| h | the observer to remove |
| virtual void dht::client::observer_remove | ( | dht::event_observer * | h, | |
| int | event_mask | |||
| ) | [virtual] |
Removes observer.
| h | the observer to remove | |
| event_mask | mask of events from which to remove |
| virtual void dht::client::connect | ( | dht::notify_handler * | handler = NULL |
) | [pure virtual] |
Connects client to DHT.
| handler | Optional handler to call when connect finished/failed. |
Instead of using the handler to get notified of connection, it is often better to add an observer for state changes to get notified when in connected state
Implemented in dht::kadc::client.
| virtual void dht::client::disconnect | ( | dht::notify_handler * | handler = NULL |
) | [pure virtual] |
Disconnects client from DHT.
| handler | The handler to call when disconnect finished/failed. |
Instead of using the handler to get notified of disconnect, it is often better to add an observer for state changes to get notified when in disconnected state
Implemented in dht::kadc::client.
| virtual void dht::client::find | ( | const dht::key & | fkey, | |
| dht::search_handler * | handler | |||
| ) | [pure virtual] |
Searches the DHT for value matching the given key.
| fkey | The key to search | |
| handler | The handler which is notified when a value is found and also finally when search is finished. If the same key/value pair is found many times from the DHT, the handler is allowed to be called more than once for the same key/value pair. |
Implemented in dht::kadc::client.
| virtual void dht::client::store | ( | const dht::key & | skey, | |
| const dht::value & | svalue, | |||
| dht::notify_handler * | handler = NULL | |||
| ) | [pure virtual] |
Stores a value to DHT.
| skey | The key that can be used to find the value | |
| svalue | The value to store into DHT | |
| handler | The handler which is notified when storing the value is done. A successfull store does not have to mean the value can be immediately retrieved from the DHT using find(). |
Implemented in dht::kadc::client.
| virtual const addr_inet_type& dht::client::external_addr | ( | ) | [pure virtual] |
Gets client's external address.
Returns the IP address of the client as seen by other participants of the network. If the address can not be detected, should point to INADDR_NONE address. Calling the function must be safe when connected, is allowed to throw an exception in other states.
Implemented in dht::kadc::client.
| virtual int dht::client::process | ( | time_value_type & | max_wait | ) | [pure virtual] |
Does DHT specific processing.
| max_wait | Maximum time to wait |
The max_wait value is decremented to reflect how much time this call took. For instance, if a time value of 3 seconds is passed to process and an event occurs after 2 seconds, max_wait will equal 1 second. This can be used if an application wishes to handle events for some fixed amount of time.
Implemented in dht::kadc::client.
| virtual int dht::client::process | ( | time_value_type * | max_wait = NULL |
) | [pure virtual] |
Does DHT specific processing.
| max_wait | Maximum time to wait or NULL if indefinite. |
The max_wait value is decremented to reflect how much time this call took. For instance, if a time value of 3 seconds is passed to process and an event occurs after 2 seconds, max_wait will equal 1 second. This can be used if an application wishes to handle events for some fixed amount of time.
Implemented in dht::kadc::client.
| virtual reactor_type* dht::client::reactor | ( | ) | [pure virtual] |
Returns the reactor which is used for event demultiplexing.
Besides calling process(), where implementations usually should use internally (ACE's) reactor for its processing needs, the application can directly call reactor. The DHT implementation registers the events it looks for to the reactor and thus will be notified accordingly if the application is running in an reactor loop. Calling directly the reactor is an alternative to using process() and usually the recommended way if the application needs to look for other I/O events besides the DHT. See ACE documentation for information on reactor usage.
By default implementations should use ACE_Reactor::instance() as their reactor unless otherwise set by the application.
Implemented in dht::kadc::client.
| virtual void dht::client::reactor | ( | reactor_type * | reactor | ) | [pure virtual] |
Sets the reactor which is used for event demultiplexing.
| reactor | The reactor DHT implementation should use. |
By default implementations should use ACE_Reactor::instance() as their reactor unless otherwise set by the application.
Implemented in dht::kadc::client.
| virtual int dht::client::handler_cancel | ( | dht::notify_handler * | handler | ) | [pure virtual] |
cancels a handler
| handler | the handler to cancel |
Implemented in dht::kadc::client.
1.5.1