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

Constructor Summary

JMemory(java.nio.ByteBuffer peer)

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

void	check() Checks if this peered object is initialized.
protected void	cleanup() Called to clean up and release any allocated memory.
protected void	finalize() Default finalizer which checks if there is any memory to free up.
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()
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.
protected void	setSize(int size) Changes the size of this memory block.
int	size() Returns the size of the memory block that this peered structure is point to.
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

Methods inherited from class java.lang.Object

clone, equals, 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

Constructor Detail

JMemory

public JMemory(java.nio.ByteBuffer peer)

Parameters:

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 -

JMemory

public JMemory(JMemory.Type type)

No memory pre-allocation constructor

Method Detail

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

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.

finalize

protected void finalize()

Default finalizer which checks if there is any memory to free up.

Overrides:

finalize in class java.lang.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

isOwner

public final boolean isOwner()

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 cleanup() method to ensure that this object no longer references memory which may have been or become deallocated.

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.

Throws:

PeeringException

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

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

Throws:

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

setSize

protected void setSize(int size)

Changes the size of this memory block. The size can not be changed passed the physical size.

Parameters:

size - length in bytes for this memory buffer

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

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

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

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

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