The read and write handling have some basic asymmetry, so the abstraction
layer's data and the interface to the code that requests reads and writes
will be different depending on which direction the data is going, but
the basic poll-and-call-handler pattern in the main loop will be the
same either way.

What I'd like to do is something like this:
--------
/*in overlapped.h*/
struct overlapped_cookie
{
    sync_type need_attention;
    struct overlapped_data *internal;

    /*Continue with initialization*/

    /*Continue with initialization*/

The idea is that the main loop can do something like:
--------
/*These arrays are populated by other code to keep an up-to-date list of
    reads and writes (possibly to be extended to other events) that are
    being waited for
*/
sync_type sync[N];
int (*handler[N])(struct overlapped_cookie *);
struct overlapped_cookie *all_overlapped[N];

/*main loop, minus error handling:*/
while(!are_we_done_yet())
{
    int which_one=do_wait(sync,num_filled);
    handler[which_one](all_overlapped[which_one]);

I have two questions about this:

(1) Is it legal and well-defined for external code to use a pointer to
the same incomplete struct type for what is actually different types
in different translation units, as long as no read struct ever gets
passed to the write functions and no write struct ever gets passed to
the read functions?
(I'm fairly sure, but not certain, that the struct pointer representation
requirements make this valid.)

(2) Is this considered acceptable, maintainable, and not aesthetically
unpleasant by other C programmers?  Or, at least, no worse than the
alternative of forcing the main poll loop to handle reads and writes
separately?
(This one I'm not so sure about.)

(2b) Is there a better way to do this?

dave

    Another approach might be to rearrange things a bit.
Instead of having the overlapped_cookie struct point at
different varieties of overlapped_data structures, make
the overlapped_cookie be the first element of both flavors
of overlapped_data:

        struct overlapped_cookie {
            sync_type need_attention;
            /* any other externally-visible stuff
             * that you always want
             */
        };

In the internals of the read and write implementations:

        struct overlapped_read_data {
            struct overlapped_cookie cookie;
            /* internal stuff specific to read */
        };

and

        struct overlapped_write_data {
            struct overlapped_cookie cookie;
            /* internal stuff specific to write */
        };

    Your external interface would traffic in pointers to
struct overlapped_cookie objects, which are elements of
the struct overlapped_*_data objects allocated internally.
Thanks to 6.7.2.1p13 it is permissible to convert a struct
pointer to a pointer to its first element and vice versa,
so an internal function can convert a cookie pointer to
a pointer to the struct that contains it.

    It's still a matter of taste, but I find the second
approach far more palatable than the first.