content specific APIs More...

#include "xcache.h"

Functions
int	XbufInit (XcacheBuf *xbuf)
	initialize an Xcache buffer More...

int	XbufAdd (XcacheBuf xbuf, void data, size_t len)
	appends data to an XcacheBuf More...

void	XbufFree (XcacheBuf *xbuf)
	frees the contents of an XcacheBuf More...

int	XcacheHandleDestroy (XcacheHandle *h)
	destroy an XcacheHandle More...

int	XcacheHandleInit (XcacheHandle *h)
	initialize an XcacheHandle More...

int	XcacheHandleSetTtl (XcacheHandle *h, time_t ttl)
	set TTL for newly created chunks More...

int	XevictChunk (XcacheHandle h, const char cid)
	evict a chunk from the local content cache More...

int	XputChunk (XcacheHandle h, const char data, size_t length, sockaddr_x *addr)
	load a chunk into the local content cache More...

int	XputMetaChunk (XcacheHandle h, sockaddr_x metachunk, sockaddr_x *addrs, socklen_t addrlen, int count)
	create and cache a chunk consisting of addresses of other chunks More...

int	XputFile (XcacheHandle h, const char fname, size_t chunkSize, sockaddr_x **addrs)
	breaks a file into a series of chunks More...

int	XputBuffer (XcacheHandle h, const char data, size_t length, size_t chunkSize, sockaddr_x **addrs)
	breaks a large buffer into a series of chunks More...

int	XbufPut (XcacheHandle h, XcacheBuf xbuf, size_t chunkSize, sockaddr_x **addrs)
	breaks the contents of an XcacheBuf into chunks More...

int	XfetchChunk (XcacheHandle h, void buf, int flags, sockaddr_x addr, socklen_t len)
	fetch a chunk from the network More...

int	XregisterNotif (int event, void(func)(XcacheHandle , int event, sockaddr_x *addr, socklen_t addrlen))
	register to receive notifications when chunks arrive More...

int	XlaunchNotifThread (XcacheHandle *h)
	fetch a partial chunk More...

int	XreadChunk (XcacheHandle h, sockaddr_x addr, socklen_t addrlen, void *buf, size_t buflen, off_t offset)
	fetch a partial chunk More...

Function Documentation

int XbufAdd	(	XcacheBuf *	xbuf,
		void *	data,
		size_t	len
	)

Reallocates the storage inside the Xcachebuf and appends data to it.

Parameters

xbuf	pointer to a new XcacheBuf to intialize

Returns: 0 on success; -1 on error with xbuf unchanged

void XbufFree ( XcacheBuf * xbuf )

Frees the contents of an XcacheBuf.

Parameters

xbuf	pointer to a XcacheBuf to free

int XbufInit ( XcacheBuf * xbuf )

Initializes the fields in an XcacheBuf to default values.

Note: This does not currently reset a previously allocated XcacheBuf.

Parameters

xbuf	pointer to a new XcacheBuf to intialize

Returns: 0 on success; -1 if xbuf is NULL

int XbufPut	(	XcacheHandle *	h,
		XcacheBuf *	xbuf,
		size_t	chunkSize,
		sockaddr_x **	addrs
	)

inline

Chunks the contents of xbuf into one or more chunks each containing up to chunkSize bytes.

Calls XputBuffer() internally.

Parameters

h	the cache handle
xbuf	the XcachedBuf to be cached
chunkSize	the maximum size for each chunk. If chunksize is 0, the default size of 1mb per chunk will be used.
addrs	pointer to a variable which will receive the array of DAGs that refer to the newly created chunks. The memory pointered to by addr should be freed by the calling code.

Returns: the number of chunks created; -1 with errno set appropriately if an error occurs

int XcacheHandleDestroy ( XcacheHandle * h )

Closes the sockets associated with h and clears internal state.

Parameters

h	handle to destroy

int XcacheHandleInit ( XcacheHandle * h )

Prepare an XcacheHandle for use.

Parameters

h	handle to initialize

Returns: 0 on success; -1 on error

int XcacheHandleSetTtl	(	XcacheHandle *	h,
		time_t	ttl
	)

Sets the Time To Live (TTL) in seconds for all chunks created with this XcacheHandle. This only applies to chunks created after the TTL has been set. The default value (0) is to live forever.

Parameters

h	XcacheHandle to modify
ttl	time to live in seconds.

Returns: 0 on success; -1 on error

int XevictChunk	(	XcacheHandle *	h,
		const char *	cid
	)

Evicts a chunk from the local content cache.

Note: this only applies to the system the command is run on. It does not affect any other hosts or routers where this chunk may be cached.

Parameters

h	cache handle
CID	of the chunk to evict Either the full CID (CID:nnnnnn) or just the hash (nnnnnn) is valid.

Returns: XCACHE_OK on success; XCACHE_INVALID_CID if cid is not properly formed; -1 if a communication error with the xcache daemon occurs

int XfetchChunk	(	XcacheHandle *	h,
		void **	buf,
		int	flags,
		sockaddr_x *	addr,
		socklen_t	len
	)

Fetches the specified chunk from the network. The chunk is retrieved from the origin server specified in addr unless it is found in the local cache or on one of the in-path routers between the client and server. Because the CID of a chunk is the hash of the content, a chunk can safely be returned from an intermediate router that is closer to the client than the origin server.

Note: non-blocking fetches have not been extensively tested and may not work as expected

Parameters

h	the cache handle
buf	a variable to recieve a pointer to the chunk's data. The value in buf should be freed when the caller is through with it.
flags	bitmap of options to use when retrieving the chunk XCF_BLOCK (RECOMMENDED TO BE SET) block until the entire chunk has arrived then return it to the caller XCF_DISABLENOTIF (not currently used) XCF_CACHE if set cache the chunk locally as well as return it to the caller
addr	the DAG of the chunk to retreive
len	the size of the memory pointed to by addr (should be sizeof(sockaddr_x))

Returns: 0 on success; -1 with errno set appropriately if an error occurs

int XlaunchNotifThread ( XcacheHandle * h )

Start a thread to receive notifications when chunks requested using the XcacheHandle h arrive.

Note: this API is not currently working correctly,

Parameters

h	the cache handle used when XfetchChunk was called

Returns: 0 on success; an error code on failure (see the man page for pthread_create() for more details)

int XputBuffer	(	XcacheHandle *	h,
		const char *	data,
		size_t	length,
		size_t	chunkSize,
		sockaddr_x **	addrs
	)

Chunks the buffer into one or more chunks each containing up to chunkSize bytes. A block of memory large enough to hold the list of new DAGs is created and should be freed by the calling code when it is done with the addresses. Each DAG is in the form of "RE (AD HID) CID". A route for each chunk's CID is added to the node's routing table. The chunks will expire out of the local cache (and any other locations where it is subsequently cached) if a TTL has been set in in the XcacheHandle.

Parameters

h	the cache handle
data	the buffer to cache
the	length of data
chunkSize	the maximum size for each chunk. If chunksize is 0, the default size of 1mb per chunk will be used.
addrs	pointer to a variable which will receive the array of DAGs that refer to the newly created chunks. The memory pointered to by addr should be freed by the calling code.

Returns: the number of chunks created; -1 with errno set appropriately if an error occurs

int XputChunk	(	XcacheHandle *	h,
		const char *	data,
		size_t	length,
		sockaddr_x *	addr
	)

Creates a CID based on the hash of the content supplied in data, caches the chunk locally, and returns a DAG in the form of "RE (AD HID) CID" that refers to the local address of the newly created chunk. A route to the CID is added to the node's routing table. The chunk will expire out of the local cache (and any other locations where it is subsequently cached) if a TTL has been set in in the XcacheHandle.

Parameters

h	the cache handle
data	a byte array of data to be converted to a chunk
length	the number of bytes in data
addr	sockaddr_x to receive the DAG that points to the new chunk

Returns: XCACHE_OK on success; XCACHE_ERR_EXISTS if the chunk already resides in the cache; -1 if a communication error with the xcache daemon occurs

int XputFile	(	XcacheHandle *	h,
		const char *	fname,
		size_t	chunkSize,
		sockaddr_x **	addrs
	)

Chunks the file fname into one or more chunks each containing up to chunkSize bytes. A block of memory large enough to hold the list of new DAGs is created and should be freed by the calling code when it is done with the addresses. Each DAG is in the form of "RE (AD HID) CID". A route for each chunk's CID is added to the node's routing table. The chunks will expire out of the local cache (and any other locations where it is subsequently cached) if a TTL has been set in in the XcacheHandle.

Parameters

h	the cache handle
fname	the file to cache
chunkSize	the maximum size for each chunk. If chunksize is 0, the default size of 1mb per chunk will be used.
addrs	pointer to a variable which will receive the array of DAGs that refer to the newly created chunks. The memory pointered to by addr should be freed by the calling code.

Returns: the number of chunks created; -1 with errno set appropriately if a file error occurs

int XputMetaChunk	(	XcacheHandle *	h,
		sockaddr_x *	metachunk,
		sockaddr_x *	addrs,
		socklen_t	addrlen,
		int	count
	)

Creates a content chunk that contain a list of DAGs pointing to other CIDs The meta chunk is cached locally, and a DAG in the form of "RE (AD HID) CID" that refers to the local address of the meta chunk is returned. A route to the meta chunk's CID is added to the node's routing table. The meta chunk will expire out of the local cache (and any other locations where it is subsequently cached) if a TTL has been set in in the XcacheHandle.

Note: This function should be modified to condense the space required for each sockaddr_x otherwise the chunk will consist of a large amount of unused space.

Parameters

h	the cache handle
metachunk	pointer to a sockaddr_x that will recieve the address of the new meta chunk
addrs	an array of DAGs (most like=ly for CIDs) to be stored in the meta chunk
addrlen	the size of a sockaddr_x (FIXME: why is this needed?)
count	the number of addrs to add to the meta chunk

Returns: XCACHE_OK on success; XCACHE_ERR_EXISTS if the chunk already resides in the cache; -1 if a communication error with the xcache daemon occurs

int XreadChunk	(	XcacheHandle *	h,
		sockaddr_x *	addr,
		socklen_t	addrlen,
		void *	buf,
		size_t	buflen,
		off_t	offset
	)

Depricated, use XfetchChunk() instead.

Parameters

h	the cache handle
addr	the DAG of the chunk to retreive
addrlen	the size of the memory pointed to by addr (should be sizeof(sockaddr_x))
buf	location to copy the chunk data
buflen	size of buf
offset	location inside of the chunk to copy from

Returns: # of bytes returned in buf; -1 with errno set appropriately if an error occurs

int XregisterNotif	(	int	event,
		void()(XcacheHandle , int event, sockaddr_x *addr, socklen_t addrlen)	func
	)

Start a thread to receive notifications when chunks requested using the XcacheHandle h arrive.

Note: this API is not currently working correctly,

Parameters

h	the cache handle used when XfetchChunk was called
event	the type of event to return notificatioins for. It is not clear what the difference between these events is. XCE_CHUNKARRIVED XCE_CHUNKAVAILABLE
addr	the DAG of the chunk to receive notifications for
addrlen	the length of addr (should be sizeof(sockaddr_x))

Returns: 0 on success; an error code on failure (see the man page for pthread_create() for more details)

Functions

Function Documentation