org.jnetpcap.nio
Class JMemory

java.lang.Object
  org.jnetpcap.nio.JMemory

Direct Known Subclasses:

JBuffer, JFunction, JMemoryPool.Block, JNumber, JStruct

public abstract class JMemory
extends java.lang.Object

A base class for all other PEERED classes to native c structures. The class only contains the physical address of the native C structure. The class also contains a couple of convenience methods for allocating memory for the structure to be peered as well as doing cleanup and freeing up that memory when object is finalized().

This is one of the most important classes within jNetPcap library. It is responsible for most of the memory allocation and management behind the scenes of all jNetPcap native methods.

Since:

1.2

Author:

Mark Bednarczyk, Sly Technologies, Inc.

Nested Class Summary

static class

JMemory.Type Used in special memory allocation.

Field Summary

static java.lang.String	JNETPCAP_LIBRARY_NAME Name of the native library that wraps around libpcap and extensions.
static long	MAX_DIRECT_MEMORY_DEFAULT The default maximum value for 'nio.mx' system property, if not set.
static JMemory.Type	POINTER Convenience constant that is synonym as JMemory.Type.POINTER.

Constructor Summary

JMemory(java.nio.ByteBuffer peer)
Instantiates a new j memory.

JMemory(int size)
Pre-allocates memory for any structures the subclass may need to use.

JMemory(JMemory.Type type)
No memory pre-allocation constructor.

JMemory(JMemory src)
Performs a deep copy into a newly allocated memory block.

Method Summary

static long	availableDirectMemory() Returns how much native memory is available for allocation.
void	check() Checks if this peered object is initialized.
protected void	cleanup() Called to clean up and release any allocated memory.
protected JMemoryReference	createReference(long address, long size) Creates a cleanup/dispose weak reference object.
boolean	isInitialized() Checks if this peered object is initialized.
boolean	isJMemoryBasedOwner() Checks if physical memory pointed to by this object, is owned either by this JMemory based object or the actual owner is also JMemory based.
boolean	isOwner() Checks if this object is the owner of native memory
static long	maxDirectMemory() Returns the hard limit for the amount of memory native is allowed to allocate.
protected int	peer(java.nio.ByteBuffer peer) Peers the src structure with this instance.
protected int	peer(JMemory peer) Peers the peer structure with this instance.
protected int	peer(JMemory peer, int offset, int length) Peers the peer structure with this instance.
static long	reservedDirectMemory() Returns how much native memory has be used so far.
void	setSize(int size) Changes the size of the current memory buffer.
int	size() Returns the size of the memory block that this peered structure is point to.
static long	softDirectMemory() Returns the soft limit for native memory allocation.
java.lang.String	toDebugString() Returns a debug string about this JMemory state.
java.lang.String	toHexdump() A debug method, similar to toString() which converts the contents of the memory to textual hexdump.
java.lang.String	toHexdump(int length, boolean address, boolean text, boolean data) A debug method, similar to toString() which converts the contents of the memory to textual hexdump.
static long	totalActiveAllocated() Returns the total number of active native memory bytes currently allocated that have not been deallocated as of yet.
static long	totalAllocateCalls() Returns total number of allocate calls through JMemory class.
static long	totalAllocated() Returns total number of bytes allocated through JMemory class.
static long	totalAllocatedSegments0To255Bytes() Returns the number of memory segments that were allocated by JMemory class in the range of 0 to 255 bytes in size.
static long	totalAllocatedSegments256OrAbove() Returns the number of memory segments that were allocated by JMemory class in the range of 256 bytes or above in size.
static long	totalDeAllocateCalls() Returns total number of deallocate calls through JMemory class.
static long	totalDeAllocated() Returns total number of bytes deallocated through JMemory class.
protected int	transferFrom(byte[] buffer) Copies contents of byte array to memory.
protected int	transferFrom(byte[] buffer, int srcOffset, int length, int dstOffset) Copies contents of byte array to memory.
protected int	transferFrom(java.nio.ByteBuffer src) Copies data from memory from direct byte buffer to this memory.
protected int	transferFrom(java.nio.ByteBuffer src, int dstOffset) Copies data from memory from direct byte buffer to this memory.
protected int	transferFromDirect(java.nio.ByteBuffer src, int dstOffset) Copies data from memory from direct byte buffer to this memory.
protected boolean	transferOwnership(JMemory memory) A special method that allows one object to transfer ownership of a memory block.
protected int	transferTo(byte[] buffer) Copies data from memory to byte array.
protected int	transferTo(byte[] buffer, int srcOffset, int length, int dstOffset) Copies data from memory to byte array.
int	transferTo(java.nio.ByteBuffer dst) Copies teh contents of this memory to buffer.
int	transferTo(java.nio.ByteBuffer dst, int srcOffset, int length) Copies teh contents of this memory to buffer.
int	transferTo(JBuffer dst, int srcOffset, int length, int dstOffset) Transfers the contents of this memory to buffer.
protected int	transferTo(JMemory dst) Copied the entire contents of this memory to destination memory.
protected int	transferTo(JMemory dst, int srcOffset, int length, int dstOffset) Copied the entire contents of this memory to destination memory.
protected static int	transferTo0(long address, byte[] buffer, int srcOffset, int length, int dstOffset) Transfer to0.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

JNETPCAP_LIBRARY_NAME

public static final java.lang.String JNETPCAP_LIBRARY_NAME

Name of the native library that wraps around libpcap and extensions.

See Also:

Constant Field Values

MAX_DIRECT_MEMORY_DEFAULT

public static final long MAX_DIRECT_MEMORY_DEFAULT

The default maximum value for 'nio.mx' system property, if not set. The actual runtime default value for 'nio.mx' property is calculated to be the lower of either MAX_DIRECT_MEMORY_DEFAULT constant or the value specified on the JVM command line using '-Xmx' option.

See Also:

Constant Field Values

POINTER

public static final JMemory.Type POINTER

Convenience constant that is synonym as JMemory.Type.POINTER. Since this type constant is used so often, it is made as a in-class constant to make it easier to access.

Constructor Detail

JMemory

public JMemory(java.nio.ByteBuffer peer)

Instantiates a new j memory.

Parameters:

peer - the peer

JMemory

public JMemory(int size)

Pre-allocates memory for any structures the subclass may need to use.

Parameters:

size - number of bytes to pre-allocate allocate

JMemory

public JMemory(JMemory src)

Performs a deep copy into a newly allocated memory block.

Parameters:

src - the src

JMemory

public JMemory(JMemory.Type type)

No memory pre-allocation constructor.

Parameters:

type - type of memory allocation model

Method Detail

availableDirectMemory

public static long availableDirectMemory()

Returns how much native memory is available for allocation. This is a limit set by method setMaxDirectMemorySize(long).

Returns:

the difference between maxDirectMemory and reservedDirectMemory

maxDirectMemory

public static long maxDirectMemory()

Returns the hard limit for the amount of memory native is allowed to allocate. The memory setting defaults to JVMs max memory which can be specified with JVM command line option '-Xmx<size>.Once the 'nio.mx' limit is reached, the allocating thread is blocked and a JVM GC request is issued. The allocating thread continues to wait, until sufficient minimum amount (Default: DisposableGC#MIN_MEMORY_RELEASE)of native memory was cleaned up or a timeout (Default:

Returns:

the limit in number of bytes DisposableGC#OUT_OF_MEMORY_TIMEOUT ms) occurs.

This limit can be set at startup of the application using the following system properties, which are checked in the order listed below:

1. org.jnetsoft.nio.MaxDirectMemorySize
2. nio.MaxDirectMemorySize
3. org.jnetsoft.nio.mx
4. nio.mx

The different property names, from the most fully qualified to the least, are provided to property name conflict resolution. For convenience, it is recommended that the user choose the least qualified property name to use. In the unlikely event that another library within the same runtime application uses the same property name, one of the more qualified (or longer) property names can be used to resolve the conflict.

reservedDirectMemory

public static long reservedDirectMemory()

Returns how much native memory has be used so far.

Returns:

amount of memory reserved/allocated at this moment

softDirectMemory

public static long softDirectMemory()

Returns the soft limit for native memory allocation. When the soft memory allocation limit is reached, memory continues to be allocated without interruption or blocking. At the same the a JVM GC request is issued to start collecting unused objects and potentially cleanup memory. The JVM GC request may be repeated while the current memory allocation is above this soft limit, but is limited to a minimum delay between consecutive JVM GC requests. This process continues until memory allocation falls below this soft limit or the hard 'nio.mx' limit is reached.

This limit can be set at startup of the application using the following system properties, which are checked in the order listed below:

1. org.jnetsoft.nio.SoftDirectMemorySize
2. nio.SoftDirectMemorySize
3. org.jnetsoft.nio.ms
4. nio.ms

The different property names, from the most fully qualified to the least, are provided to property name conflict resolution. For convenience, it is recommended that the user choose the least qualified property name to use. In the unlikely event that another library within the same runtime application uses the same property name, one of the more qualified (or longer) property names can be used to resolve the conflict.

Returns:

the amount of memory, in bytes, before we start requesting a forcible JVM GC.

totalActiveAllocated

public static long totalActiveAllocated()

Returns the total number of active native memory bytes currently allocated that have not been deallocated as of yet. This number can be calculated by the following formula:

 totalAllocated() - totalDeAllocated()
 

Returns:

number of native memory bytes still allocated

totalAllocateCalls

public static long totalAllocateCalls()

Returns total number of allocate calls through JMemory class. The memory is allocated by JMemory class using native "malloc" calls and is not normally reported by JRE memory usage.

Returns:

total number of function calls made to malloc since JMemory class was loaded into memory

totalAllocated

public static long totalAllocated()

Returns total number of bytes allocated through JMemory class. The memory is allocated by JMemory class using native "malloc" calls and is not normally reported by JRE memory usage.

Returns:

total number of bytes allocated since JMemory class was loaded into memory

totalAllocatedSegments0To255Bytes

public static long totalAllocatedSegments0To255Bytes()

Returns the number of memory segments that were allocated by JMemory class in the range of 0 to 255 bytes in size. This is number of segments, not amount of memory allocated.

Returns:

the total number of memory segments in this size

totalAllocatedSegments256OrAbove

public static long totalAllocatedSegments256OrAbove()

Returns the number of memory segments that were allocated by JMemory class in the range of 256 bytes or above in size. This is number of segments, not amount of memory allocated.

Returns:

the total number of memory segments in this size

totalDeAllocateCalls

public static long totalDeAllocateCalls()

Returns total number of deallocate calls through JMemory class. The memory is allocated by JMemory class using native "free" calls and is not normally reported by JRE memory usage.

Returns:

total number of function calls made to free since JMemory class was loaded into memory

totalDeAllocated

public static long totalDeAllocated()

Returns total number of bytes deallocated through JMemory class. The memory is deallocated by JMemory class using native "free" calls and is not normally reported by JRE memory usage.

Returns:

total number of bytes deallocated since JMemory class was loaded into memory

transferTo0

protected static int transferTo0(long address,
                                 byte[] buffer,
                                 int srcOffset,
                                 int length,
                                 int dstOffset)

Transfer to0.

Parameters:

address - the address

buffer - the buffer

srcOffset - the src offset

length - the length

dstOffset - the dst offset

Returns:

the int

check

public void check()
           throws java.lang.IllegalStateException

Checks if this peered object is initialized. This method throws IllegalStateException if not initialized and does not return any values. Its intended to as an assert mechanism

Throws:

java.lang.IllegalStateException - if peered object is not initialized this unchecked exception will be thrown, otherwise it will exit silently

cleanup

protected void cleanup()

Called to clean up and release any allocated memory. This method should be overriden if the allocated memory is not simply a single memory block and something more complex. This method is safe to call at anytime even if the object does not hold any allocated memory or is not the owner of the memory it is peered with. The method will reset this object to orignal unpeered state releasing any allocated and own memory at the same time if neccessary.

createReference

protected JMemoryReference createReference(long address,
                                           long size)

Creates a cleanup/dispose weak reference object. This reference object is responsible for cleanup, after the actual JMemory object is garbage collected. After this object is garbage collected, the dispose method on the returned JMemoryReference object will be called at some point, when this object on longer exists, to cleanup. All JMemoryReferences contain a native memory pointer to the memory that potentially needs cleanup and disposal.

This method is protected and allows subclasses to provide their own cleanup code. If this method is not overriden, it will return a JMemoryReference object suitable to cleanup after this memory object.

Parameters:

address - native memory address to use in the disposable

size - the size

Returns:

a reference that is tied to this JMemory object

isInitialized

public boolean isInitialized()

Checks if this peered object is initialized. This method does not throw any exceptions.

Returns:

if initialized true is returned, otherwise false

isJMemoryBasedOwner

public boolean isJMemoryBasedOwner()

Checks if physical memory pointed to by this object, is owned either by this JMemory based object or the actual owner is also JMemory based. This method provides a check if the physical memory pointed to by this object has been allocated through use of one of JMemory based functions or outside its memory management scope. For example, memory allocated by libpcap library will return false. While packets that copied their state to new memory will return true.

Returns:

true if physical memory is managed by JMemory, otherwise false

isOwner

public final boolean isOwner()

Checks if this object is the owner of native memory

Returns:

true if this object is the owner, otherwise false

peer

protected int peer(java.nio.ByteBuffer peer)
            throws PeeringException

Peers the src structure with this instance. The physical memory that the src peered object points to is set to this instance. The owner flag is not copied and src remains at the same state as it did before. This instance does not become the owner of the memory.

Further more, since we are peering with a ByteBuffer, the actual memory that is peered is between ByteBuffer's position and limit properties. Those 2 properties determine which portion of the memory that will be peered. This allows a larger ByteBuffer to be peered with different objects providing rudimentary memory allocation mechanism.

Lastly care must be taken, to ensure that the lifespans do not conflict. The memory that we are peering to must not be deallocated prior the termination of the lifespan of this object or at minimum calling

Parameters:

peer - The ByteBuffer whose allocated native memory we want to peer with. The ByteByffer must be if direct buffer type which can be checked using ByteBuffer.isDirect() call.

Returns:

the int

Throws:

PeeringException - the peering exception cleanup() method to ensure that this object no longer references memory which may have been or become deallocated.

See Also:

ByteBuffer.isDirect()

peer

protected int peer(JMemory peer)

Peers the peer structure with this instance. The physical memory that the peer object points to is set to this instance. The owner flag is not copied and peer remains at the same state as it did before. This instance does not become the owner of the memory.

Parameters:

peer - the object whose allocated native memory we want to peer with

Returns:

the int

peer

protected int peer(JMemory peer,
                   int offset,
                   int length)
            throws java.lang.IndexOutOfBoundsException

Peers the peer structure with this instance. The physical memory that the peer object points to is set to this instance. The owner flag is not copied and peer remains at the same state as it did before. This instance does not become the owner of the memory. The function allows peering to a sub portion of the peer given the specified offset and length. The function strictly checks and inforces the bounds of the request to guarrantee that peer is not allowed to access physical memory outside of actual peer range.

Parameters:

peer - object memory block to peer with

offset - offset into the memory block

length - amount of memory to peer with

Returns:

the int

Throws:

java.lang.IndexOutOfBoundsException - if the specified memory offset and length have negative or out of bounds of peer objects address space

setSize

public void setSize(int size)

Changes the size of the current memory buffer. The size can only be reduced in length and can not grow. The method throws exceptions if size parameter is greater then current size or negative.

Parameters:

size - size in bytes that is smaller then existing size

size

public int size()

Returns the size of the memory block that this peered structure is point to. This object does not neccessarily have to be the owner of the memory block and could simply be a portion of the over all memory block.

Returns:

number of byte currently allocated

toDebugString

public java.lang.String toDebugString()

Returns a debug string about this JMemory state. Example:

 JMemory@b052fa8: size=1506, owner=nio.JMemoryPool$Block.class(size=10240/offset=4064)
 

• hex nuber, is physical memory location
• size = number of bytes of this memory object
• owner = the class name of the object that owns the physical memory
• isOwner = if true, means that this object is the owner of physical memory
• size in parenthesis = the size of the physical memory allocated by the owner
• offset in parenthesis = the offset into the physical memory block of this memory object

Returns:

a summary string describing the state of this memory object

toHexdump

public java.lang.String toHexdump()

A debug method, similar to toString() which converts the contents of the memory to textual hexdump.

Returns:

multi-line hexdump of the entire memory region

toHexdump

public java.lang.String toHexdump(int length,
                                  boolean address,
                                  boolean text,
                                  boolean data)

A debug method, similar to toString() which converts the contents of the memory to textual hexdump.

Parameters:

length - maximum number of bytes to dump to hex output

address - flag if set to true will print out address offset on every line

text - flag if set to true will print out a text characters at the end of everyline

data - flag if set to true will print out raw HEX data on every line

Returns:

multi-line hexdump of the entire memory region

transferFrom

protected int transferFrom(byte[] buffer)

Copies contents of byte array to memory.

Parameters:

buffer - source buffer

Returns:

number of bytes copied

transferFrom

protected int transferFrom(byte[] buffer,
                           int srcOffset,
                           int length,
                           int dstOffset)

Copies contents of byte array to memory.

Parameters:

buffer - source buffer

srcOffset - starting offset into the byte array

length - number of bytes to copy

dstOffset - starting offset into memory buffer

Returns:

number of bytes copied

transferFrom

protected int transferFrom(java.nio.ByteBuffer src)

Copies data from memory from direct byte buffer to this memory.

Parameters:

src - source buffer

Returns:

actual number of bytes that was copied

transferFrom

protected int transferFrom(java.nio.ByteBuffer src,
                           int dstOffset)

Copies data from memory from direct byte buffer to this memory.

Parameters:

src - source buffer

dstOffset - offset into our memory location

Returns:

actual number of bytes that was copied

transferFromDirect

protected int transferFromDirect(java.nio.ByteBuffer src,
                                 int dstOffset)

Copies data from memory from direct byte buffer to this memory.

Parameters:

src - source buffer

dstOffset - offset into our memory location

Returns:

actual number of bytes that was copied

transferOwnership

protected boolean transferOwnership(JMemory memory)

A special method that allows one object to transfer ownership of a memory block. The supplied JMemory object must already be the owner of the memory block. This policy is strictly enforced. If the ownership transfer succeeds, this memory object will be responsible for freeing up memory block when this object is garbage collected or the user calls JMemory.cleanup() method.

Warning!

Care must be taken to only transfer ownership for simple memory allocations. If a complex memory allocation was used, one that sub allocates other memory blocks which are referenced from the original memory block, to avoid creating memory leaks. It is best practice to sub allocate other memory blocks using JMemory class which will properly manage that memory block and ensure that it will freed properly as well.

Parameters:

memory - memory block to transfer the ownership from

Returns:

if tranfer succeeded true is returned, otherwise false.

transferTo

protected int transferTo(byte[] buffer)

Copies data from memory to byte array.

Parameters:

buffer - destination buffer starting offset in byte array

Returns:

number of bytes copied

transferTo

protected int transferTo(byte[] buffer,
                         int srcOffset,
                         int length,
                         int dstOffset)

Copies data from memory to byte array.

Parameters:

buffer - destination buffer

srcOffset - starting offset in memory

length - number of bytes to copy

dstOffset - starting offset in byte array

Returns:

number of bytes copied

transferTo

public int transferTo(java.nio.ByteBuffer dst)

Copies teh contents of this memory to buffer.

Parameters:

dst - destination buffer

Returns:

actual number of bytes that was copied

transferTo

public int transferTo(java.nio.ByteBuffer dst,
                      int srcOffset,
                      int length)

Copies teh contents of this memory to buffer.

Parameters:

dst - destination buffer

srcOffset - offset in source

length - number of bytes to copy

Returns:

number of bytes copied

transferTo

public int transferTo(JBuffer dst,
                      int srcOffset,
                      int length,
                      int dstOffset)

Transfers the contents of this memory to buffer.

Parameters:

dst - destination buffer

srcOffset - offset in source

length - number of bytes to copy

dstOffset - offset in destination buffer

Returns:

number of bytes copied

transferTo

protected int transferTo(JMemory dst)

Copied the entire contents of this memory to destination memory.

Parameters:

dst - destination memory

Returns:

number of bytes copied

transferTo

protected int transferTo(JMemory dst,
                         int srcOffset,
                         int length,
                         int dstOffset)

Copied the entire contents of this memory to destination memory.

Parameters:

dst - destination memory

srcOffset - offset in source

length - number of bytes to copy

dstOffset - offset in destination buffer

Returns:

number of bytes copied