harmony-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Paulex Yang <paulex.y...@gmail.com>
Subject Proposal to extend portlib with enhanced mmap functions:
Date Wed, 26 Jul 2006 09:28:35 GMT
Hi, all

I raise HARMONY-982 (https://issues.apache.org/jira/browse/HARMONY-982) 
about the portlib extension on mmap. And here goes my proposal about the 
extension, comments are welcome.

Currently portlib has some mmap support, but the support is limited in 
several ways:
1. it only mmap in private(copy_on_write) mode
2. it always mmap whole file
3. it only accepts filename, but nio needs to map a already opened file 
descriptor

so that the Harmony's mmap is implemented in platform dependent codes so 
far, I think these are good candidates as the portlib extension.

To support the nio's requirement, three current mmap functions need to 
be enhanced - hymmap_map_file, hymmap_unmap_file and 
hymmap_capabilities, one new method is added: hymmap_msync. Please see 
details below:

1. hymmap_map_file

/**
 * Map a part of file into memory.
 *
 * @param [in]  portLibrary           The port library
 * @param [in]  file                  The file descriptor/handle of the 
already open file to be mapped
 * @param [in]  offset                The file offset of the part to be 
mapped
 * @param [in]  size                  The number of bytes to be mapped, 
if zero, the whole file is mapped
 * @param [in]  mappingName           The name of the file mapping 
object to be created/opened.
 *                                                         If a named 
object is not required, this parameter can be specified as NULL
 * @param [in]   flags                Flags relating to the mapping:
 * @args                                         
HYPORT_MMAP_FLAG_READ                read only map
 * @args                                         
HYPORT_MMAP_FLAG_WRITE               read/write map
 * @args                                         
HYPORT_MMAP_FLAG_COPYONWRITE         copy on write map
 * @args                                         
HYPORT_MMAP_FLAG_SHARED              share memory mapping with other 
processes
 * @args                                         
HYPORT_MMAP_FLAG_PRIVATE             private memory mapping, do not 
share with other processes (implied by HYPORT_MMAP_FLAG_COPYONWRITE)
 *
 * @return                            A pointer to the start of the 
mapped file or NULL is an error has occurred
 */
void *hymmap_map_file(HYPortLibrary portLibrary, IDATA file, U_64 
offset, UDATA size, const char *mappingName, U_32 flags)

This will use CreateFileMapping() and MapViewOfFile() on Windows and 
mmap() on Unix to map the file into the process' address space.  In both 
cases, it will return the address to which the file has been mapped.

The memory mapping API's on all platforms require an open handle/file 
descriptor to the file to be mapped.

The mapAddress parameter has been removed from the original signature.  
This was an output parameter from the API containing the address at 
which the file has been mapped.  However, this is the return value of 
the function and was therefore duplication.

2. hymmap_msync

/**
 * Synchronise updates to memory mapped file region with file on disk.  
The call may wait for the file write
 * to complete or this may be scheduled for a later time and the 
function return immediately, depending on
 * the flags setting
 *
 * @param [in]  portLibrary             The port library
 * @param [in]  start                   Pointer to the start of the 
memory mapped area to be synchronised
 * @param [in]  length                  Length of the memory mapped area 
to be synchronised
 * @param [in]  flags                   Flags controlling the behaviour 
of the function:
 * @args                                           
HYPORT_MMAP_SYNC_WAIT   Synchronous update required, function will not
 *                                                                     
return until file updated.  Note that to achieve this on Windows 
requires the
 *                                                                     
file to be opened with the FILE_FLAG_WRITE_THROUGH flag
 * @args                                           
HYPORT_MMAP_SYNC_ASYNC Asynchronous update required, function returns
 *                                                                    
immediately, file will be updated later
 * @args                                           
HYPORT_MMAP_SYNC_INVALIDATE Requests that other mappings of the same
 *                                                                    
file be invalidated, so that they can be updated with the values just 
written
 *
* @return                               0 on success, -1 on failure.  
Errors will be reported using the usual port library mechanism
 */
IDATA hymmap_msync(HYPortLibrary portLibrary, void *start, UDATA length, 
U_32 flags)

This function will use msync on Unix and FlushViewOfFile on Windows.

3. hymmap_unmap_file

/**
 * Unmap previously mapped memory
 *
 * @param [in]  portLibrary             The port library
 * @param [in]  start                   Pointer to the start of the 
memory mapped area
 * @param [in]  size                    The length of the mapped area
 */
void hymmap_unmap_file(HYPortLibrary portLibrary, void *start, UDATA size)

This existing API will be changed to take the start address returned 
from hymmap_map_file and the size of the mapped area instead of the 
current handle.  The handle is not very clear as it is the start address 
of the mapped area (equivalent to start) on Windows and a pointer to a 
structure containing this and the size on Unix platforms.  Explicitly 
passing the start address and length will provide a clearer interface.

4. hymmap_capabilities

/**
 * Check the capabilities available for HYMMAP at runtime for the 
current platform
 *
 * @param [in]  portLibrary         The port library
 *
 * @return                          The capabilities available on this 
platform
 * @args                                            
HYPORT_MMAP_CAPABILITY_READ
 * @args                                            
HYPORT_MMAP_CAPABILITY_WRITE
 * @args                                            
HYPORT_MMAP_CAPABILITY_COPYONWRITE
 */
I_32 hymmap_capabilities(HYPortLibrary portLibrary)

-- 
Paulex Yang
China Software Development Lab
IBM



---------------------------------------------------------------------
Terms of use : http://incubator.apache.org/harmony/mailing.html
To unsubscribe, e-mail: harmony-dev-unsubscribe@incubator.apache.org
For additional commands, e-mail: harmony-dev-help@incubator.apache.org


Mime
View raw message