Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_mmap.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef APR_MMAP_H
00017 #define APR_MMAP_H
00018 
00019 /**
00020  * @file apr_mmap.h
00021  * @brief APR MMAP routines
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_pools.h"
00026 #include "apr_errno.h"
00027 #include "apr_ring.h"
00028 #include "apr_file_io.h"        /* for apr_file_t */
00029 
00030 #ifdef BEOS
00031 #include <kernel/OS.h>
00032 #endif
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif /* __cplusplus */
00037 
00038 /**
00039  * @defgroup apr_mmap MMAP (Memory Map) Routines
00040  * @ingroup APR 
00041  * @{
00042  */
00043 
00044 /** MMap opened for reading */
00045 #define APR_MMAP_READ    1
00046 /** MMap opened for writing */
00047 #define APR_MMAP_WRITE   2
00048 
00049 /** @see apr_mmap_t */
00050 typedef struct apr_mmap_t            apr_mmap_t;
00051 
00052 /**
00053  * @remark
00054  * As far as I can tell the only really sane way to store an MMAP is as a
00055  * void * and a length.  BeOS requires this area_id, but that's just a little
00056  * something extra.  I am exposing this type, because it doesn't make much
00057  * sense to keep it private, and opening it up makes some stuff easier in
00058  * Apache.
00059  */
00060 /** The MMAP structure */
00061 struct apr_mmap_t {
00062     /** The pool the mmap structure was allocated out of. */
00063     apr_pool_t *cntxt;
00064 #ifdef BEOS
00065     /** An area ID.  Only valid on BeOS */
00066     area_id area;
00067 #endif
00068 #ifdef WIN32
00069     /** The handle of the file mapping */
00070     HANDLE mhandle;
00071     /** The start of the real memory page area (mapped view) */
00072     void *mv;
00073     /** The physical start, size and offset */
00074     apr_off_t  pstart;
00075     apr_size_t psize;
00076     apr_off_t  poffset;
00077 #endif
00078     /** The start of the memory mapped area */
00079     void *mm;
00080     /** The amount of data in the mmap */
00081     apr_size_t size;
00082     /** ring of apr_mmap_t's that reference the same
00083      * mmap'ed region; acts in place of a reference count */
00084     APR_RING_ENTRY(apr_mmap_t) link;
00085 };
00086 
00087 #if APR_HAS_MMAP || defined(DOXYGEN)
00088 
00089 /** @def APR_MMAP_THRESHOLD 
00090  * Files have to be at least this big before they're mmap()d.  This is to deal
00091  * with systems where the expense of doing an mmap() and an munmap() outweighs
00092  * the benefit for small files.  It shouldn't be set lower than 1.
00093  */
00094 #ifdef MMAP_THRESHOLD
00095 #  define APR_MMAP_THRESHOLD              MMAP_THRESHOLD
00096 #else
00097 #  ifdef SUNOS4
00098 #    define APR_MMAP_THRESHOLD            (8*1024)
00099 #  else
00100 #    define APR_MMAP_THRESHOLD            1
00101 #  endif /* SUNOS4 */
00102 #endif /* MMAP_THRESHOLD */
00103 
00104 /** @def APR_MMAP_LIMIT
00105  * Maximum size of MMap region
00106  */
00107 #ifdef MMAP_LIMIT
00108 #  define APR_MMAP_LIMIT                  MMAP_LIMIT
00109 #else
00110 #  define APR_MMAP_LIMIT                  (4*1024*1024)
00111 #endif /* MMAP_LIMIT */
00112 
00113 /** Can this file be MMaped */
00114 #define APR_MMAP_CANDIDATE(filelength) \
00115     ((filelength >= APR_MMAP_THRESHOLD) && (filelength < APR_MMAP_LIMIT))
00116 
00117 /*   Function definitions */
00118 
00119 /** 
00120  * Create a new mmap'ed file out of an existing APR file.
00121  * @param newmmap The newly created mmap'ed file.
00122  * @param file The file turn into an mmap.
00123  * @param offset The offset into the file to start the data pointer at.
00124  * @param size The size of the file
00125  * @param flag bit-wise or of:
00126  * <PRE>
00127  *          APR_MMAP_READ       MMap opened for reading
00128  *          APR_MMAP_WRITE      MMap opened for writing
00129  * </PRE>
00130  * @param cntxt The pool to use when creating the mmap.
00131  */
00132 APR_DECLARE(apr_status_t) apr_mmap_create(apr_mmap_t **newmmap, 
00133                                           apr_file_t *file, apr_off_t offset,
00134                                           apr_size_t size, apr_int32_t flag,
00135                                           apr_pool_t *cntxt);
00136 
00137 /**
00138  * Duplicate the specified MMAP.
00139  * @param new_mmap The structure to duplicate into. 
00140  * @param old_mmap The mmap to duplicate.
00141  * @param p The pool to use for new_mmap.
00142  */         
00143 APR_DECLARE(apr_status_t) apr_mmap_dup(apr_mmap_t **new_mmap,
00144                                        apr_mmap_t *old_mmap,
00145                                        apr_pool_t *p);
00146 
00147 /**
00148  * Remove a mmap'ed.
00149  * @param mm The mmap'ed file.
00150  */
00151 APR_DECLARE(apr_status_t) apr_mmap_delete(apr_mmap_t *mm);
00152 
00153 /** 
00154  * Move the pointer into the mmap'ed file to the specified offset.
00155  * @param addr The pointer to the offset specified.
00156  * @param mm The mmap'ed file.
00157  * @param offset The offset to move to.
00158  */
00159 APR_DECLARE(apr_status_t) apr_mmap_offset(void **addr, apr_mmap_t *mm, 
00160                                           apr_off_t offset);
00161 
00162 #endif /* APR_HAS_MMAP */
00163 
00164 /** @} */
00165 
00166 #ifdef __cplusplus
00167 }
00168 #endif
00169 
00170 #endif  /* ! APR_MMAP_H */

Generated on Sat Apr 2 21:46:29 2005 for Apache Portable Runtime by  doxygen 1.3.9.1