opaque "pointer" API, model, best practice ?

hi all, is there an api / usage model / or best practice for opaque "handles" ? Im aware of 1 case: the handle returned by zs_malloc I have tried to use it, and have run into locking conflicts when trying to keep the memory zs_mapped longer than the duration of a function. OTOH, if I map and unmap within the function, things work, but this is unacceptable overhead. so I figure I should read some good code, rather than keep hacking at bad code.