libdill: Structured Concurrency for C

NAME

hquery - gets an opaque pointer associated with a handle and a type

SYNOPSIS

#include <libdillimpl.h>

void *hquery(int h, const void *type);

DESCRIPTION

Returns an opaque pointer associated with the passed handle and type. This function is a fundamental construct for building APIs on top of handles.

The type argument is not interpreted in any way. It is used only as a unique ID. A unique ID can be created, for instance, like this:

int foobar_placeholder = 0;
const void *foobar_type = &foobar_placeholder;

The return value has no specified semantics. It is an opaque pointer. One typical use case for it is to return a pointer to a table of function pointers. These function pointers can then be used to access the handle's functionality:

struct foobar_vfs {
    int (*foo)(struct foobar_vfs *vfs, int a, int b);
    void (*bar)(struct foobar_vfs *vfs, char *c);
};

int foo(int h, int a, int b) {
    struct foobar_vfs *vfs = hquery(h, foobar_type);
    if(!vfs) return -1;
    return vfs->foo(vfs, a, b);
}

int foo(int h, char *c) {
    struct foobar_vfs *vfs = hquery(h, foobar_type);
    if(!vfs) return -1;
    vfs->bar(vfs, c);
    return 0;
}

Pointers returned by hquery are meant to be cachable. In other words, if you call hquery on the same handle with the same type multiple times, the result should be the same.

RETURN VALUE

Returns an opaque pointer on success. On error, NULL is returned and errno is set to one of the following values.

ERRORS

EXAMPLE

struct foobar_vfs *vfs = hquery(h, foobar_type);