Class: ExternalBytes

• Inheritance
• Description
• Related information
• Class protocol
  • initialization
  • instance creation
  • instance release
  • malloc debug
  • queries
• Instance protocol
  • accessing
  • compatibility-VW
  • converting
  • filling & replacing
  • finalization
  • freeing
  • pointer arithmethic
  • printing & storing
  • private-accessing
  • private-allocation
  • queries
  • registration
  • resizing
• Examples

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ExternalBytes
                  |
                  +--ExternalLong
                  |
                  +--ExternalStructure
                  |
                  +--MappedExternalBytes
                  |
                  +--UnprotectedExternalBytes

Package:

stx:libbasic

Category:

System-Support

Version:

rev: 1.78 date: 2010/04/08 11:57:17

user: cg

file: ExternalBytes.st directory: libbasic

module: stx stc-classLibrary: libbasic

Author:

Claus Gittinger

Description:

This class provides access to any memory in the system. Its main purpose
is to provide a baseclass for objects referencing structured external data.
Normally, instances are created by primitive code which wants to pass C-data
to Smalltalk AND grants smalltalk access to individual bytes afterwards.
Primitives which do not want to grant this access should return instances of
ExternalAddress. See more info there. Also, have a look at ExternalFunction
which is another similar class, but specialized to represent callable C-functions.

Since the memory address of an instance stays fixed (once allocated),
it can also be used to share data with external C-parts
(which are not prepared for objects to change their address).

Use with great care - access is not always checked for out-of-bounds
or valid addresses.

Since the data is allocated outside the garbage collected smalltalk space,
its address stays fix. Thus, it can be passed to external C-functions without
any danger. However, you have to take care for freeing the memory yourself.

To help in avoiding memory bugs, instances created with #new: are
registered in a local classvar and deregistered when the underlying memory
is explicitely freed. Since a life reference (from that classvar) exists,
the garbage collector will never find these to be reclaimable, and the
underlying memory stays allocated (at a fix address) forever.
To release the memory, either #free it or #unprotect it.
The first will immediately release the memory, while the second will delay
freeing until the next garbage collect occurs.

If you need memory which is automatically freed, create
the instance via #unprotectedNew: right away; the underlying malloced-memory
will be released as soon as no smalltalk reference to the ExtBytes object
exists any more (however, you have to know for sure, that no C-references
exist to this memory).

To release all memory call #releaseAllMemory which simply sets the
AllocatedInstances class variable to nil (thus releasing those refs).

Example (automatic freeing as soon as ref to buffer is gone):
    |buffer|

    buffer := ExternalBytes unprotectedNew:100.
    ...


Example (manual freeing - never freed, if ref to buffer is gone):
    |buffer|

    buffer := ExternalBytes new:100.
    ...
    buffer free


Example (delayed automatic freeing as soon as ref to buffer is gone):
    |buffer|

    buffer := ExternalBytes new:100.
    ...
    buffer unregister

This class only supports unstructured external data
- see the companion class ExternalStructure for more.

Notice: support for external data is still being developed -
        a parser for C structure syntax and typedefs is on the way,
        making shared data with C programs much easier in the future.

Also notice, that this class may not be available or behave different
in other smalltalk systems, making code using it very unportable.
It is provided for C interfacing only.

Finally note, that ST/X's memory system is much faster than malloc/free
in the normal case - especially for short term temporary objects,
automatically reclaimed object memory is about 5-10 times faster than
malloc/free.
Things may be different for huge byte-valued objects, which are to be
reclaimed by the oldspace colletor.
Anyway, for portability, we strongly warn from using this as a substitute
for byteArrays; it is meant for shared data with external C-functions ONLY.

Debugging:
    since all manual memory systems are subject of obscure errors,
    you may want to turn malloc-tracing on; this traces all allocations/frees
    done here. To do this, evaluate: 'ExternalBytes mallocTrace:true'.

    In addition, you may turn on full debugging (with 'ExternalBytes mallocDebug:true');
    if turned on, all malloc/realloc requests are remembered and later free / realloc
    requests validated against this list (i.e. to detect freeing unallocated chunks).

    To benefit from this in C-code, we recommend you use __stx_malloc() / __stx_free()
    instead of malloc() / free(). To do so, redefine them in a header file (or cc comand line)
    and recompile your external c-libraries with this.

    I used this here to find memory leaks in the Xt libraries (there are still some in
    the HTML widget ...). If mallocDebug is on, #dumpMallocChunks will print out what is
    leftOver. This may help to find trouble spots in your C-code.

Related information:

    ExternalAddress
    ExternalFunction
    ByteArray
    [how to write primitive code]

Class protocol:

 initialize

 address: aNumber

return a new ExternalBytes object to access bytes starting at aNumber.
The memory at aNumber has been allocated elsewhere. The size is not known,
therefore byte accesses will NOT be checked for valid index.
Use this, if you get a pointer from some external source (such as a
C-callBack function) and you have to extract bytes from that.

DANGER ALERT: this method allows very bad things to be done to the
system - use with GREAT care (better: do not use it)

 address: aNumber size: size

return a new ExternalBytes object to access bytes starting at aNumber.
The memory at aNumber has been allocated elsewhere. The size is known,
which allows byte accesses to be checked for valid index.
Use this, if you get a pointer to a structure from some external source
(such as a C-callBack function) and you have to extract things from that.

DANGER ALERT: this method allows very bad things to be done to the
system - use with GREAT care (better: do not use it)

 new: numberOfBytes

allocate some memory usable for data;
the memory is not controlled by the garbage collector.
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).

Use this, if you have to pass a block of bytes to some
external destination (such as a C function) which does not copy the
data, but instead keeps a reference to it. For example, many functions
which expect strings simply keep a ref to the passed string - for those,
an ST/X string-pointer is not the right thing to pass, since ST/X objects
may change their address.

DANGER ALERT: the memory is NOT automatically freed until it is either
MANUALLY freed (see #free) or the returned externalBytes object
is unprotected or the classes releaseAllMemory method is called.

 newNullTerminatedFromString: aString

 unprotectedNew: numberOfBytes

allocate some memory usable for data;
the memory is under the control of the garbage collector.
Return a corresponding ExternalBytes object or raise MallocFailure (if malloc fails).

DANGER ALERT: the memory block as allocated will be automatically freed
as soon as the reference to the returned externalBytes object
is gone (by the next garbage collect).
If the memory has been passed to a C-function which
remembers this pointer, bad things may happen ....

 releaseAllMemory

 dumpMallocChunks

 freeAllMallocChunks

free all stx_malloc'd memory. Be careful, this does no validation at all;
It simply walks through all chunks and frees them unconditionally.
This may be helpful during debugging memory-leaks, to release memory which
was not correctly freed by C-code. Howeve, only memory which was allocated
by __stx_malloc() is freed here - so you better compile your primitive code with
malloc redefined to stx_malloc.
Also, mallocDebug has to be on to do this.

 mallocDebug: aBoolean

 mallocStatistics

 mallocTrace: aBoolean

 numberOfAllocatedChunks

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned.

 sizeofDouble

return the number of bytes used by the machines native doubles

 sizeofFloat

return the number of bytes used by the machines native floats

 sizeofInt

return the number of bytes used by the machines native integer

 sizeofLong

return the number of bytes used by the machines native longs

 sizeofPointer

return the number of bytes used by the machines native pointer

 sizeofShort

return the number of bytes used by the machines native short

Instance protocol:

 address

return the start address as an integer

 basicAt: index

return the byte at index, anInteger;
Indices are 1-based, therefore
this is the byte at (address + index - 1)

 basicAt: index put: value

set the byte at index, anInteger to value which must be 0..255.
Returns value (sigh).
Indices are 1-based, therefore
this is the byte at (address + index - 1)

 byteAt: index

return the unsigned byte at index, anInteger.
Indices are 1-based, therefore
this is the byte at (address + index - 1)

 byteAt: index put: aByteValuedInteger

set the byte at index.
Indices are 1-based, therefore
this is the byte at (address + index - 1)

 instVarAt: index

redefined to suppress direct access to my address, which is a non-object

 copyCStringFromHeap

 asExternalAddress

return the start address as an external address

 asExternalBytes

 replaceBytesFrom: start to: stop with: aCollection startingAt: repStart

replace elements from another collection, which must be a ByteArray-
like collection.

Notice: This operation modifies the receiver, NOT a copy;
therefore the change may affect all others referencing the receiver.

 executor

redefined to return a lightweight copy
- all we need is the memory handle and the size.

 finalizationLobby

answer the registry used for finalization.
ExternalBytes have their own Registry

 finalize

some ExternalBytes object was finalized;
free the associated heap memory with it

 free

free a previously allocated piece of memory - be very careful, there
are no checks done here. All dangers you usually have with malloc/free
are present here ...

 register

register the receiver to be automatically finalized by the GC

 referenceToBytesFrom: start to: stop

answer a new ExternalBytes referencing a range within the receiver.
BE CAREFUL: after the receiver has been freed, the new ExternalBytes
contents is undefined

 displayString

return a printed representation of the receiver for displaying

 invalidateReference

clear the start address and size

 setAddress: aNumber size: sz

set the start address and size

 setSize: sz

set the size - warning: dangerous if wrong

 allocateBytes: numberOfBytes

allocate (malloc) numberOfBytes; if doClear is true, the allocated memory is cleared.
Fail if already allocated.
Raise MallocFailure if malloc fails to allocate enough memory

 allocateBytes: numberOfBytes clear: doClear

allocate (malloc) numberOfBytes; if doClear is true, the allocated memory is cleared.
Fail if already allocated.
Raise MallocFailure if malloc fails to allocate enough memory

 basicSize

we do not know how many bytes are valid

 isValid

true if I gave an address

 species

when copying, or concatenating, return instances of this class

 protectFromGC

enter a reference to the receiver into the AllocatedInstances
class variable - this prevents it from ever being finalized by
the garbage collector, thus protecting the underlying memory.

 unprotectFromGC

remove the receiver from the AllocatedInstances
class variable - if there is no other reference to the receiver,
the next garbage collect will finalize the receiver and the underlying
memory be freed.

 grow: numberOfBytes

reallocate (realloc) numberOfBytes.
Raise MallocFailure if realloc fails to allocate enough memory

Examples: