dht::kadc::client Class Reference

Implementation of DHT that uses KadC library. More...

#include <dht/kadc/client.h>

Inheritance diagram for dht::kadc::client:

List of all members.

Public Member Functions
virtual	~client ()
	Destructor.
const char *	init_file ()
	returns KadC's initialisation file path
virtual void	init (const name_value_map &opts)
	Initialisation of KadC.
virtual void	deinit ()
	Deinitialises.
virtual void	connect (dht::notify_handler *handler=NULL)
	Connects client to DHT.
virtual void	disconnect (dht::notify_handler *handler=NULL)
	Disconnects client from DHT.
virtual void	find (const dht::key &fkey, dht::search_handler *handler)
	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)
	Stores a value to DHT.
virtual const addr_inet_type &	external_addr ()
	Gets client's external address.
virtual int	process (time_value_type &max_wait)
	Does DHT specific processing.
virtual int	process (time_value_type *max_wait=NULL)
	Does DHT specific processing.
virtual reactor_type *	reactor ()
	Returns the reactor which is used for event demultiplexing.
virtual void	reactor (reactor_type *reactor)
	Sets the reactor which is used for event demultiplexing.
virtual int	handler_cancel (notify_handler *handler)
	cancels a handler
size_t	find_threads (size_t t)
	Sets number of threads used for find operations.
size_t	find_threads () const
	Gets number of threads used for find operations.
size_t	find_duration (size_t s)
	Sets the duration of find operation in seconds.
size_t	find_duration () const
	Gets the duration of find operation in seconds.
size_t	store_threads (size_t t)
	Sets number of threads used for store operations.
size_t	store_threads () const
	Gets number of threads used for store operations.
size_t	store_duration (size_t s)
	Sets the duration of store operation in seconds.
size_t	store_duration () const
	Gets the duration of store operation in seconds.
int	write_inifile (const char *target_file=NULL)
	Writes KadC's initialization file to disk.
size_t	contacted_nodes () const
	returns number of nodes that have been contacted successfully
size_t	contacts () const
	returns total number of contacts
Static Public Member Functions
static void	logfile (const std::string &path)
	Sets KadC log file location.

---

Detailed Description

Implementation of DHT that uses KadC library.

This implementation of dht::client interface uses KadC C-library under the hood. KadC provides access to eDonkey's Overnet network.

KadC uses for initialization a file that contains list of contact nodes to other possible peers. This file has to be given as options in initialization. KadC distribution has an example of the file.

A little code snippet example:

 #include <dht/kadc/client.h>
 
 int main() {
    dht::kadc::client client
    dht::name_value_map conf;
 
    conf.set("init_file", "kadc.ini");
    client.init(conf);
    do_stuff(client);
    return 0;
 }

Overnet and KadC and therefore this implemenatation also supports metadata.

See also:

KadC homepage http://kadc.sourceforge.net/

---

Constructor & Destructor Documentation

virtual dht::kadc::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 from dht::client.

---

Member Function Documentation

const char* dht::kadc::client::init_file

(

)

[inline]

returns KadC's initialisation file path

virtual void dht::kadc::client::init

(

const name_value_map &

opts

)

[virtual]

Initialisation of KadC.

Supported keys in dht::kadc::client:

• init_file

Implements dht::client.

virtual void dht::kadc::client::deinit

(

)

[virtual]

Deinitialises.

Since KadC's deinitialisation can take several seconds, it is not done in destructor as deleting instance should be as fast as possible. This function can be called instead. The function returns only after deinitialisation has been done.

Note that if you call disconnect and wait until state changes to disconnected, deinitialisation of KadC will be done at the same time. Disconnecting is the recommended way.

See also:

disconnect()

virtual void dht::kadc::client::connect

(

dht::notify_handler *

handler = NULL

)

[virtual]

Connects client to DHT.

Parameters:

handler

Optional handler to call when connect finished/failed.

Function returns immediately, success or failure is notified separately once in process().

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

Implements dht::client.

virtual void dht::kadc::client::disconnect

(

dht::notify_handler *

handler = NULL

)

[virtual]

Disconnects client from DHT.

Parameters:

handler

The handler to call when disconnect finished/failed.

Function returns immediately, success or failure is notified separately once in process().

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

Implements dht::client.

virtual void dht::kadc::client::find	(	const dht::key &	fkey,
		dht::search_handler *	handler
	)			[virtual]

Searches the DHT for value matching the given key.

Parameters:

	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.

See also:

search_handler

Implements dht::client.

virtual void dht::kadc::client::store	(	const dht::key &	skey,
		const dht::value &	svalue,
		dht::notify_handler *	handler = NULL
	)			[virtual]

Stores a value to DHT.

Parameters:

	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().

See also:

search_handler

Implements dht::client.

virtual const addr_inet_type& dht::kadc::client::external_addr

(

)

[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.

Implements dht::client.

virtual int dht::kadc::client::process

(

time_value_type &

max_wait

)

[virtual]

Does DHT specific processing.

Parameters:

max_wait

Maximum time to wait

The function does DHT specific processing only for maximum of time specified with max_wait. It must return if an event that triggers calling a handler or observer happens. It is allowed to call several handlers at one go if several events happen at the same time. It is also allowed to return earlier even if no events that cause calling of a handler happens. Consider max_wait as a hint how long the application is willing 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.

See also:

reactor()

Implements dht::client.

virtual int dht::kadc::client::process

(

time_value_type *

max_wait = NULL

)

[virtual]

Does DHT specific processing.

Parameters:

max_wait

Maximum time to wait or NULL if indefinite.

The function does DHT specific processing only for maximum of time specified with max_wait. It must return if an event that triggers calling a handler or observer happens. It is allowed to call several handlers at one go if several events happen at the same time. It is also allowed to return earlier even if no events that cause calling of a handler happens. Consider max_wait as a hint how long the application is willing 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.

See also:

reactor()

Implements dht::client.

virtual reactor_type* dht::kadc::client::reactor

(

)

[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.

Implements dht::client.

virtual void dht::kadc::client::reactor

(

reactor_type *

reactor

)

[virtual]

Sets the reactor which is used for event demultiplexing.

Parameters:

reactor

The reactor DHT implementation should use.

Besides calling process(), which 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.

Implements dht::client.

virtual int dht::kadc::client::handler_cancel

(

notify_handler *

handler

)

[virtual]

cancels a handler

Parameters:

handler

the handler to cancel

If a handler has been registered for calling, for example in connect(), disconnect() or find(), then it can be cancelled by calling this function. If called the specified handler won't be called.

Implements dht::client.

size_t dht::kadc::client::find_threads

(

size_t

t

)

[inline]

Sets number of threads used for find operations.

Parameters:

t

number of threads to use or 0 for KadC default

KadC is thread based. With this parameter you can set how many threads are used when a find operation is done.

size_t dht::kadc::client::find_threads

(

)

const [inline]

Gets number of threads used for find operations.

Can be 0 for default value.

size_t dht::kadc::client::find_duration

(

size_t

s

)

[inline]

Sets the duration of find operation in seconds.

Parameters:

s

number of seconds or 0 for KadC default

size_t dht::kadc::client::find_duration

(

)

const [inline]

Gets the duration of find operation in seconds.

Can be 0 if KadC default used.

size_t dht::kadc::client::store_threads

(

size_t

t

)

[inline]

Sets number of threads used for store operations.

Parameters:

t

number of threads to use or 0 for KadC default

KadC is thread based. With this parameter you can set how many threads are used when a store operation is done.

size_t dht::kadc::client::store_threads

(

)

const [inline]

Gets number of threads used for store operations.

Can be 0 for default value.

size_t dht::kadc::client::store_duration

(

size_t

s

)

[inline]

Sets the duration of store operation in seconds.

Parameters:

s

number of seconds or 0 for KadC default

size_t dht::kadc::client::store_duration

(

)

const [inline]

Gets the duration of store operation in seconds.

Can be 0 if KadC default used.

int dht::kadc::client::write_inifile

(

const char *

target_file = NULL

)

Writes KadC's initialization file to disk.

Parameters:

target_file

Path to file or if not specified/NULL then the one that was used for initialization

Returns:

0 if success, otherwise KadC error code

KadC keeps a list of contact nodes that has to be fed to the implementatino during startup (using init() function). This list of contact nodes is updated during operation so that the list is kept up-to-date with fresh contacts and non-responsive contacts are removed.

When disconnected or deinitializing this list is written back to disk. In case the current list is wanted to be saved in middle of operation, this function can be called.

size_t dht::kadc::client::contacted_nodes

(

)

const

returns number of nodes that have been contacted successfully

size_t dht::kadc::client::contacts

(

)

const

returns total number of contacts

static void dht::kadc::client::logfile

(

const std::string &

path

)

[static]

Sets KadC log file location.

Parameters:

path

path to the log file

Exceptions:

io_error

thrown if the log file specified couldn't be opened for writing

By default KadC logging is written to STDERR. If you call this function with a valid path then the log is written to the file specified.

This is a static function and thus affects all KadC instances.

---

The documentation for this class was generated from the following file:

• kadc/client.h

---