cp_socket

Section: cp_httpclient (3)
Updated: MAY 2006
Index Return to Main Contents

NAME

cp_httpclient_ctl, cp_httpclient_ctl_create, cp_httpclient_ctl_destroy, cp_httpcilent_ctl_get_pollfds - http client api

SYNOPSIS

#include <sys/poll.h>
#include <cprops/httpclient.h>

cp_httpclient_ctl *cp_httpclient_ctl_create(int background);
void cp_httpclient_ctl_destroy(cp_httpclient_ctl *ctl);

struct pollfd *
cp_httpclient_ctl_get_pollfds(cp_httpclient_ctl *ctl, int *num);

On systems without poll(2)

#include <sys/select.h>
#include <cprops/httpclient.h>

fd_set *
cp_httpclient_ctl_get_read_fd_set(cp_httpclient_ctl *ctl, int *num);
fd_set *
cp_httpclient_ctl_get_write_fd_set(cp_httpclient_ctl *ctl, int *num);

DESCRIPTION

The default fetch functions group all http requests in one of two execution stacks - the asynchronous transfer stack or the asynchronous background transfer stack which differs in that requests are executed in a separate thread. Applications may require processing requests in separate groups, or on machines with multiple cpus, it may be desireable to process requests in multiple background threads.

cp_httpclient_ctl_create creates a new execution stack. The background parameter determines the number of threads made available for processing requests. If background is 1, a background thread is started to process requests on the created controller. If background is 2 or higher, a thread pool is created to process requests with the parameter value used as the maximal pool size. If background is zero, no additional threads are started, and requests must be driven by calls to cp_httpclient_fetch_ctl_exec(3). In this case applications should poll on the struct pollfd array returned by cp_httpclient_ctl_get_pollfds with a non-zero value to prevent spinning on the call to cp_httpclient_ctl_exec. If not NULL, the num parameter to cp_httpclient_ctl_get_pollfds is set to the number of entries in the struct pollfd array.

cp_httpclient_ctl_destroy stops any threads associated with a cp_httpclient_ctl object and performs clean up.

RETURN VALUE

cp_httpclient_ctl_create returns a newly allocated cp_httpclient_ctl object on success or NULL on memory allocation failure.

cp_httpclient_ctl_get_pollfds returns an array of struct pollfd objects which may be used in a call to poll(2) or NULL on a memory allocation failure or if the transfer control stack contains no entries. In addition, if not NULL the num parameter is set to the number of entries in the array.

On systems where poll(2) is unavailable, the cp_httpclient_ctl_get_read_fd_set and cp_httpclient_ctl_get_write_fd_set are defined instead. These functions return a pointer to an fd_set structure set with the applicable file descriptors, which may be used in a call to select(). In this case the num parameter is set to the value largest file descriptor in the set rather than to the total number of file descriptors.