qalloc_makedynmap

SYNOPSIS

       #include <qthread/qalloc.h>

       void *
       qalloc_makestatmap(const off_t filesize,
                          void *addr,
                          const char *filename,
                          size_t itemsize,
                          const size_t streams);

       void *
       qalloc_makedynmap(const off_t filesize,
                         void *addr,
                         const char *filename,
                         const size_t streams);

       void *
       qalloc_loadmap(const char *filename);

DESCRIPTION

       These functions are for creating and/or loading memory maps.  The  con-
       cept  is  simple:  create  a  giant mmap()'d file on disk, and allocate
       space out of it much like a malloc(). Of course, for speed and simplic-
       ity reasons, it doesn't work *exactly* like a malloc().

       The  qalloc_makestatmap()  and  qalloc_makedynmap() functions both will
       either create a file with the specified filename, or, if  such  a  file
       already  exists, will load it. The qalloc_loadmap() function expects an
       existing file named filename, will read the necessary  information  out
       of it, and attempt to load it.

       The  files created by qalloc_makestatmap() and qalloc_makedynmap() will
       be filesize bytes long, prepared to serve streams concurrent  requests,
       and will be loaded at the address addr. addr may be NULL to indicate no
       preference. The qalloc_makestatmap() function also  takes  an  itemsize
       argument,  which specifies the size of allocations that need to be made
       from the file.

CONCEPT

       There are two kinds of on-disk maps:  dynamic  maps  and  static  maps.
       Static  maps  have very lwo overhead, but have the restriction that all
       allocations in them have the same size (also, they're slower to create,
       initially). Dynamic maps allow you to decide how much memory to use for
       each allocation at runtime, but have more overhead  both  in  terms  of
       space and time (also, they're very fast to create, initially).

       The  mmap()'d files contain mutexes to protect the allocation and deal-
       location operatoins, so the files can actually be  shared  by  multiple
       threads  or  multiple  processes.  Each  thread  is  mapped  to a given
       "stream"  (or  set  of  mutexes)  by  it's  thread  id,  obtained  from
       pthread_self().
       overhead, particularly since the common-case is expected to be that the
       file is always mmap()'d into the exact same location.

       The second option, which is what is currently done, is to simply assert
       that the file MUST be loaded at the same  location,  and  to  throw  an
       error  if  it  is not. The only reason that mmap() would refuse to load
       the file into the specified location would be if there is some conflict
       and something else is already occupying that memory. This is considered
       to be the programmer's responsibility to ensure that this does not hap-
       pen.  Additionally, if the system can use a 64-bit address space, there
       should be more than sufficient space in that address space  to  find  a
       location that never conflicts.

SEE ALSO

       qalloc_checkpoint(3),  qalloc_cleanup(3),  qalloc_free(3),
       qalloc_malloc(3)



libqthread                       NOVEMBER 2006           qalloc_makestatmap(3)