guasi

Section: generic userspace async syscall implementation (3)
Updated: 0.17
Index Return to Main Contents
 

NAME

guasi_create, guasi_free, guasi_submit, guasi_fetch, guasi_req_cancel, guasi_req_info, guasi_req_free

guasi__open, guasi__read, guasi__write, guasi__pread, guasi__pwrite, guasi__sendfile, guasi__opendir, guasi__readdir, guasi__stat, guasi__fstat, guasi__recv, guasi__recvfrom, guasi__send, guasi__sendto, guasi__accept, guasi__connect

 

SYNOPSIS

 

Core API

#include <guasi.h>

guasi_t guasi_create(int min_threads, int max_threads, int max_priority);
void guasi_free(guasi_t hctx);
guasi_req_t guasi_submit(guasi_t hctx, void *priv, void *asid, int prio,
                         guasi_syscall_t proc, int nparams, ...);
int guasi_fetch(guasi_t hctx, guasi_req_t *reqs, int nreqs, long timeo);
int guasi_req_cancel(guasi_req_t hreq);
int guasi_req_info(guasi_req_t hreq, struct guasi_reqinfo *rinf);
void guasi_req_free(guasi_req_t hreq);

 

POSIX wrappers:

#include <guasi_syscalls.h>

guasi_req_t guasi__open(guasi_t hctx, void *priv, void *asid, int prio,
                        char const *name, long flags, long mode);
guasi_req_t guasi__read(guasi_t hctx, void *priv, void *asid, int prio,
                        int fd, void *buf, size_t size);
guasi_req_t guasi__write(guasi_t hctx, void *priv, void *asid, int prio,
                         int fd, void const *buf, size_t size);
guasi_req_t guasi__pread(guasi_t hctx, void *priv, void *asid, int prio,
                          int fd, void *buf, size_t size, off_t off);
guasi_req_t guasi__pwrite(guasi_t hctx, void *priv, void *asid, int prio,
                          int fd, void const *buf, size_t size, off_t off);
guasi_req_t guasi__sendfile(guasi_t hctx, void *priv, void *asid, int prio,
                            int ofd, int ifd, off_t *off, size_t cnt);
guasi_req_t guasi__opendir(guasi_t hctx, void *priv, void *asid, int prio,
                           char const *name);
guasi_req_t guasi__readdir(guasi_t hctx, void *priv, void *asid, int prio,
                           DIR *dir);
guasi_req_t guasi__stat(guasi_t hctx, void *priv, void *asid, int prio,
                        char const *name, struct stat *sbuf);
guasi_req_t guasi__fstat(guasi_t hctx, void *priv, void *asid, int prio,
                         int fd, struct stat *sbuf);
guasi_req_t guasi__recv(guasi_t hctx, void *priv, void *asid, int prio,
                        int fd, void *buf, size_t size, int flags,
                        long timeo);
guasi_req_t guasi__recvfrom(guasi_t hctx, void *priv, void *asid, int prio,
                            int fd, void *buf, size_t size, int flags,
                            struct sockaddr *from, socklen_t *fromlen, long timeo);
guasi_req_t guasi__send(guasi_t hctx, void *priv, void *asid, int prio,
                        int fd, void const *buf, size_t size, int flags,
                        long timeo);
guasi_req_t guasi__sendto(guasi_t hctx, void *priv, void *asid, int prio,
                          int fd, void const *buf, size_t size, int flags,
                          struct sockaddr const *to, socklen_t tolen, long timeo);
guasi_req_t guasi__accept(guasi_t hctx, void *priv, void *asid, int prio,
                          int fd, struct sockaddr *addr, socklen_t *addrlen,
                          long timeo);
guasi_req_t guasi__connect(guasi_t hctx, void *priv, void *asid, int prio,
                           int fd, struct sockaddr const *addr, socklen_t addrlen,
                           long timeo);


 

DESCRIPTION

The guasi library implements a thread based generic asyncronous execution engine, to be used to give otherwise syncronous calls an asyncronous behaviour. It can be used to wrap any syncronous call, so that it can be scheduled for execution, and whose result can be fetched at later time (hence not blocking the submitter thread). The guasi library can be used as complement to standard event retrieval interfaces like poll(2), select(2) or epoll(4).

 

Structures and Types

The following structures are defined:
guasi_param_t

The guasi_param_t type is the basic type used to return asyncronous operation results, and to pass parameters to asyncronous callbacks. Its size guarantee that a pointer can be safely passed through it.

guasi_syscall_t

The guasi_syscall_t type is a function pointer type, that is used to pass asyncronous functions to guasi_submit. An asyncronous function looks like:

        guasi_param_t async_proc(void *priv, guasi_param_t const *params) {
                guasi_param_t result;
                
                ...
                return result;
        }

struct guasi_reqinfo

        struct guasi_reqinfo {
                void *priv;
                void *asid;
                guasi_param_t result;
                long error;
                int status;
        };

The struct guasi_reqinfo describes the status of a request submitted to a guasi handle. The guasi_req_info function can be used to retrieve such information from a request handle (guasi_req_t). The priv member is the same priv parameter that is passed to the guasi_submit function when the request was submitted. The asid is the request identifier, passed to guasi_submit. The result member is the result of the asyncronous operation, that is in turn, the value returned by the proc parameter of the guasi_submit function. The error member if the value or the C library errno after the proc asyncronous function execution. The status is the current status of the request. Possible values for the status member are:

GUASI_STATUS_PENDING
The request has still to be dequeued.

GUASI_STATUS_ACTIVE
The request is executing.

GUASI_STATUS_COMPLETE
The request has completed.

The result and error members are undefined until the request status reaches the GUASI_STATUS_COMPLETE value.

 

Functions (Core API)

The following functions are defined:
guasi_t guasi_create(int min_threads, int max_threads, int max_priority);

The guasi_create function creates a guasi handle to be used as a gateway for all the following guasi operations. The min_threads parameter specifies the minimum number of threads to be used in the guasi thread pool, and the max_threads parameter specifies the maximum number of threads (zero means unlimited). Since guasi requests can have different priorities, the max_priority parameter specifies the number of priorities that the new guasi handle must support. The function returns the new guasi handle if succeeded, or NULL if failed.

void guasi_free(guasi_t hctx);

The guasi_free function frees all the resources associated with the guasi handle passed in hctx.

guasi_req_t guasi_submit(guasi_t hctx, void *priv, void *asid, int prio,
guasi_syscall_t proc, int nparams, ...);

The guasi_submit function submits a new request to the guasi handle passed in hctx. The priv parameter is an opaque value that is passed as is to the proc asyncronous function. The asid is a cookie that identifies the request, and is returned by the guasi_req_info function, inside the struct guasi_reqinfo strcture. The priority of the request is passed in the prio parameter, that should range from 0 to (max_priority - 1). The nparams parameter specifies the number of arguments that follows and that will be passed to the proc asyncronous function. The function returns a request handle if succeeded, or NULL if failed.

int guasi_fetch(guasi_t hctx, guasi_req_t *reqs, int nreqs, long timeo);

The guasi_fetch function retrieves completed requests from the guasi handle passed in hctx. Up to nreqs requests are retrieved, and stored inside the reqs pointer. The timeo represent a maximum time (in milliseconds) to wait for some request to complete. If timeo is negative, the wait for completed requests will not have a time limit. The function returns the number of completed requests, or a negative number in case of error.

int guasi_req_cancel(guasi_req_t hreq);

The guasi_req_cancel function cancels a pending request specified in the hreq parameter. The function returns 0 is case of success, or a negative number in case of error.

int guasi_req_info(guasi_req_t hreq, struct guasi_reqinfo *rinf);

The guasi_req_info functions retrieves information about the request passed in the hreq parameter. The request information will be stored inside the rinf struct guasi_reqinfo pointer. The function returns 0 is case of success, or a negative number in case of error.

void guasi_req_free(guasi_req_t hreq);

The guasi_req_free function frees all the resources associated with the request handle passed in hreq.

 

Functions (POSIX wrappers)

All the POSIX wrappers functions implemented by guasi, map to the corresponding POSIX function in terms of parameters and result type. Some networking functions can have an extra timeo parameter, that can be used to specify a timeout (in milliseconds) for the operation.

 

LICENSE

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. A copy of the license is available at:

http://www.gnu.org/copyleft/lesser.html

 

AUTHOR

Developed by Davide Libenzi <davidel@xmailserver.org>

 

AVAILABILITY

The latest version of the guasi library can be found at:

http://www.xmailserver.org/guasi-lib.html

 

BUGS

There are no known bugs. Bug reports and comments to Davide Libenzi <davidel@xmailserver.org>


 

Index

NAME
SYNOPSIS
Core API
POSIX wrappers:
DESCRIPTION
Structures and Types
Functions (Core API)
Functions (POSIX wrappers)
LICENSE
AUTHOR
AVAILABILITY
BUGS

This document was created by man2html, using the manual pages.
Time: 22:42:34 GMT, February 25, 2007