Class: ExternalStructure

• Inheritance
• Description
• Class protocol
  • Compatibility-Squeak
  • instance creation
  • queries
  • utilities
• Instance protocol
  • private
  • testing

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--ExternalBytes
                  |
                  +--ExternalStructure

Package:

stx:libbasic

Category:

System-Support-External Memory

Version:

rev: 1.17 date: 2023/05/28 10:09:09

user: cg

file: ExternalStructure.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

Instances of this class represent external (non-Smalltalk) data,
typically C-structs or C++ instances.
They are only useful to represent handles as returned by C functions as smalltalk objects.

ExternallStructures are much like ExternalBytes - however, the latter
allow you to access bytes via indexed at:/at:put: messages, whilst instances of subclasses of me
allow access via the corresponding getter/setter methods of my C-type.

Usage: normally (within eXept), these are to be used with the ctype framework, which parses
c header files and generates structure descriptions (ctypes).
However, this class can also be used without such type descriptions, by subclassing it
and redefining sizeof (to return the size in bytes of the structure) and getters
(as 'self longAt:idx', unsignedLOngAt:idx, etc.).

copyright
COPYRIGHT (c) 2006 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 externalNew

 fromExternalAddress: anExternalAddress

 new

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

 protectedNew

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.

 unprotectedNew

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 ....

 cType

 fields

for Squeak compatibility support: may return a literal array structure definition,
from which the size and layout of the fields can be constructed.
Notice: in newer squeak versions, this was renamed to fieldsDesc (sigh),
so both fields and fieldsDesc are tried.
Returns nil for ST/X subclasses, which redefine the sizeof method
or provide a cType

 fieldsDesc

for Squeak compatibility support: may return a literal array structure definition,
from which the size and layout of the fields can be constructed.
Notice: in earlier squeak versions, this was called fields (sigh),
so both fields and fieldsDesc are tried.
Returns nil for ST/X subclasses, which redefine the sizeof method
or provide a cType

 sizeof

the sizeof my instances in bytes

** This method must be redefined in concrete classes (subclassResponsibility) **

 generateCTypeFromFieldDescriptionV1: fieldsSpec

to support Squeak external structures, which define a fields method,
which returns a literal array spec of (fieldName typeName) pairs

 generateCTypeFromFieldDescriptionV2: fieldsSpec

to support Squeak external structures, which define a fieldsDesc method,
which returns a literal array spec of (typeName fieldName) pairs

Instance protocol:

 fromExternalAddress: anExternalAddressOrExternalStructure

 isExternalStructure