addrlist.c File Reference

Functions
void	dpl_addrlist_lock (dpl_addrlist_t *addrlist)
	Lock a addrlist. More...
void	dpl_addrlist_unlock (dpl_addrlist_t *addrlist)
	Unlock a addrlist. More...
dpl_addr_t *	dpl_addrlist_get_byip_nolock (dpl_addrlist_t *addrlist, struct in_addr ip_addr, u_short port)
	Search a bootstrap list item associated with a given IP address and port. More...
dpl_addr_t *	dpl_addrlist_get_byname_nolock (dpl_addrlist_t *addrlist, const char *host, const char *portstr)
	Lookup a bootstrap list item associated with a given IP address and port. More...
u_int	dpl_addrlist_count_nolock (dpl_addrlist_t *addrlist)
	Count the number of items in a bootstrap list. More...
u_int	dpl_addrlist_count (dpl_addrlist_t *addrlist)
	Count the number of items in a bootstrap list. More...
u_int	dpl_addrlist_count_avail_nolock (dpl_addrlist_t *addrlist)
	Count the number of items not blacklisted in a bootstrap list. More...
dpl_status_t	dpl_addrlist_get_nth (dpl_addrlist_t *addrlist, int n, char **hostp, char **portstrp, struct in_addr *ip_addrp, u_short *portp)
	Get the nth item not blacklisted in a bootstrap list. More...
dpl_status_t	dpl_addrlist_get_rand (dpl_addrlist_t *addrlist, char **hostp, char **portstrp, struct in_addr *ip_addrp, u_short *portp)
	Get a random item not blacklisted in the bootstrap list. More...
dpl_status_t	dpl_addrlist_blacklist (dpl_addrlist_t *addrlist, const char *host, const char *portstr, time_t expiretime)
	Blacklist a host/port couple for the specified time. More...
dpl_status_t	dpl_addrlist_unblacklist (dpl_addrlist_t *addrlist, const char *host, const char *portstr)
	Un-blacklist a host/port couple previously blacklisted. More...
dpl_status_t	dpl_addrlist_refresh_blacklist_nolock (dpl_addrlist_t *addrlist)
	Refresh the bootstrap list blacklist by un-blacklisting expired entries. More...
void	dpl_addrlist_add_nolock (dpl_addrlist_t *addrlist, dpl_addr_t *addr)
	Add an item to a bootstrap list. More...
void	dpl_addrlist_remove_nolock (dpl_addrlist_t *addrlist, dpl_addr_t *addr)
	Remove an item from a bootstrap list. More...
dpl_status_t	dpl_addrlist_add (dpl_addrlist_t *addrlist, const char *host, const char *portstr)
	Add a new host/port couple to a bootstrap list. More...
void	dpl_addrlist_clear_nolock (dpl_addrlist_t *addrlist)
	Free a bootstrap list. More...
dpl_status_t	dpl_addrlist_add_from_str (dpl_addrlist_t *addrlist, const char *addrlist_str)
	Add new elements to a bootstrap list from a list of hosts/ports. More...
dpl_status_t	dpl_addrlist_set_from_str (dpl_addrlist_t *addrlist, const char *addrlist_str)
	Initialise the bootstrap list from a list of hosts/ports. More...
char *	dpl_addrlist_get (dpl_addrlist_t *addrlist)
	Get a string describing the bootstrap list. More...

Function Documentation

dpl_status_t dpl_addrlist_add	(	dpl_addrlist_t *	addrlist,
		const char *	host,
		const char *	portstr
	)

Parameters

addrlist	a bootstrap list.
host	a string corresponding to the hostname or IP address to add.
portstr	a string containing the port number to add.

Return values

DPL_FAILURE	if the addition failed.
DPL_SUCCESS	otherwise.

Returns

If the given host/port is already present in the bootstrap list, nothing will be done and DPL_SUCCESS is returned.

dpl_status_t dpl_addrlist_add_from_str	(	dpl_addrlist_t *	addrlist,
		const char *	addrlist_str
	)

Parameters

addrlist	a bootstrap list.
addrlist	a string containing a list of hosts and ports to use to populate the bootstrap list. The list is a semicolon/comma/space separated list of the form host1[:port1][; ,]...[; ,]hostn[:portn].

Note

addrlist is modified

Return values

DPL_SUCCESS	on success.
DPL_FAILURE	otherwise.

void dpl_addrlist_add_nolock	(	dpl_addrlist_t *	addrlist,
		dpl_addr_t *	addr
	)

The addrlist takes ownership of the boostrap item and will free it when appropriate.

Note

This function does not take the addrlist lock, so use with care.

Parameters

addrlist	a bootstrap list.
addr	a bootstrap item to add to the addrlist.

dpl_status_t dpl_addrlist_blacklist	(	dpl_addrlist_t *	addrlist,
		const char *	host,
		const char *	portstr,
		time_t	expiretime
	)

Parameters

addrlist	a bootstrap list.
host	a string corresponding to the hostname or IP address
portstr	a string containing the port number
expiretime	minimum duration in seconds to wait before retrying to contact the host. If -1, never retry to contact host (unblacklist the item via dpl_addrlist_unblacklist())

Return values

DPL_FAILURE	if the addition failed.
DPL_ENOENT	if matching host was not found in addrlist
DPL_SUCCESS	otherwise.

void dpl_addrlist_clear_nolock

(

dpl_addrlist_t *

addrlist

)

This will empty the bootstrap list associated with the given ring context and free all the memory associated with this list.

Parameters

addrlist

a bootstrap list.

u_int dpl_addrlist_count

(

dpl_addrlist_t *

addrlist

)

Parameters

addrlist

a bootstrap list.

Returns

the number of items in the bootstrap list.

u_int dpl_addrlist_count_avail_nolock

(

dpl_addrlist_t *

addrlist

)

Note

This function does not take the addrlist lock, so use with care.

Parameters

addrlist

a bootstrap list.

Returns

the number of items not blacklisted in the bootstrap list.

u_int dpl_addrlist_count_nolock

(

dpl_addrlist_t *

addrlist

)

Note

This function does not take the addrlist lock, so use with care.

See Also

dpl_addrlist_count()

Parameters

addrlist

a bootstrap list.

Returns

the number of items in the bootstrap list.

char* dpl_addrlist_get

(

dpl_addrlist_t *

addrlist

)

Parameters

addrlist

a bootstrap list.

Returns

NULL on failure, an empty ("\0") string if the bootstrap list was empty or a comma-separated list of host:port couples. The returned string should be freed with free() when no longer used.

dpl_addr_t* dpl_addrlist_get_byip_nolock	(	dpl_addrlist_t *	addrlist,
		struct in_addr	ip_addr,
		u_short	port
	)

Note

This function does not take the addrlist lock, so use with care.

Parameters

addrlist	a bootstrap list.
addr	IP address of the item to look for.
port	port used by the item to look for.

Returns

a dpl_addr_t with address addr and port port, or NULL if no matching item could be found in the bootstrap list. The returned object is owned by addrlist and should not be freed.

dpl_addr_t* dpl_addrlist_get_byname_nolock	(	dpl_addrlist_t *	addrlist,
		const char *	host,
		const char *	portstr
	)

Note

This function does not take the addrlist lock, so use with care.

Parameters

addrlist	a bootstrap list.
host	a string corresponding to the hostname or IP address to look for.
portstr	a string containing the port number to look for.

Returns

a dpl_addr_t matching the given host and port, or NULL if no matching item could be found in the bootstrap list. The returned object is owned by addrlist and should not be freed.

dpl_status_t dpl_addrlist_get_nth	(	dpl_addrlist_t *	addrlist,
		int	n,
		char **	hostp,
		char **	portstrp,
		struct in_addr *	ip_addrp,
		u_short *	portp
	)

Parameters

	addrlist	a bootstrap list.
	n	index of the item to look for starting at 0. If n is bigger than theh number of elements in the bootstrap list, n modulo length of bootstrap list will be looked up instead.
[out]	hostp	returned host name of the nth bootstrap list item, can be NULL. hostp must NOT be freed by the caller.
[out]	portstrp	returned port string of the nth bootstrap list item, can be NULL. portstrp must NOT be freed by the caller.
[out]	addrp	returned address of the nth bootstrap list item, can be NULL.
[out]	portp	returned port of the nth bootstrap list item, can be NULL.

Return values

DPL_ENOENT	if the bootstrap list is empty, addrp and portp will be unchanged in this case.
DPL_SUCCESS	if the operation was successful. portp/addrp will be filled if they are non-NULL.

dpl_status_t dpl_addrlist_get_rand	(	dpl_addrlist_t *	addrlist,
		char **	hostp,
		char **	portstrp,
		struct in_addr *	ip_addrp,
		u_short *	portp
	)

Parameters

	addrlist	a bootstrap list.
[out]	hostp	returned host name of the nth bootstrap list item, can be NULL. hostp must NOT be freed by the caller.
[out]	portstrp	returned port string of the nth bootstrap list item, can be NULL. portstrp must NOT be freed by the caller.
[out]	addrp	returned address of a random bootstrap list item, can be NULL.
[out]	portp	returned port of a random bootstrap list item, can be NULL.

Return values

DPL_ENOENT	if the bootstrap list is empty, addrp and portp will be unchanged in this case.
DPL_SUCCESS	if the operation was successful. portp/addrp will be filled if they are non-NULL.

void dpl_addrlist_lock

(

dpl_addrlist_t *

addrlist

)

This is useful to arbitrate concurrent access to the addrlist from different threads. If the context is already locked, this will block until the locking succeeds. The context must then be unlocked using dpl_addrlist_unlock().

Parameters

addrlist

the addrlist to lock.

dpl_status_t dpl_addrlist_refresh_blacklist_nolock

(

dpl_addrlist_t *

addrlist

)

Parameters

addrlist

a bootstrap list.

Return values

DPL_FAILURE	if the refresh failed.
DPL_SUCCESS	after a successful refresh

void dpl_addrlist_remove_nolock	(	dpl_addrlist_t *	addrlist,
		dpl_addr_t *	addr
	)

Note

This function does not take the addrlist lock, so use with care.

This function will remove the item from the bootstrap list it's part of without checking if this is the bootstrap list of the passed in ring context.

Parameters

addrlist	a bootstrap list.
addr	the bootstrap item to remove from the addrlist

dpl_status_t dpl_addrlist_set_from_str	(	dpl_addrlist_t *	addrlist,
		const char *	addrlist_str
	)

See Also

dpl_addrlist_add_from_str()

Parameters

addrlist	a bootstrap list.
addrlist	a string containing a list of hosts and ports to use to populate the bootstrap list. The list is a semicolon/comma/space separated list of the form host1[:port1][; ,]...[; ,]hostn[:portn].

Note

addrlist is not modified

Return values

DPL_SUCCESS	on failure.
DPL_FAILURE	otherwise.

dpl_status_t dpl_addrlist_unblacklist	(	dpl_addrlist_t *	addrlist,
		const char *	host,
		const char *	portstr
	)

Parameters

addrlist	a bootstrap list.
host	a string corresponding to the hostname or IP address
portstr	a string containing the port number

Return values

DPL_FAILURE	if the addition failed.
DPL_ENOENT	if matching host was not found in addrlist
DPL_SUCCESS	otherwise (if host is not already blacklisted, silently succeed)

void dpl_addrlist_unlock

(

dpl_addrlist_t *

addrlist

)

This must be done from the same thread that locked the context.

See Also

dpl_addrlist_lock

Parameters

addrlist

the addrlist to unlock.