Class: ExternalAddress

• Inheritance
• Description
• Class protocol
  • Compatibility-V'Age
  • instance creation
  • queries
• Instance protocol
  • Compatibility-Squeak
  • accessing
  • comparing
  • converting
  • finalization
  • printing & storing
  • private-accessing
  • queries
  • testing
• Examples

Inheritance:

   Object
   |
   +--ExternalAddress
      |
      +--FFIExternalObject
      |
      +--OSHandle
      |
      +--XftFontDescription::FCPatternHandle
      |
      +--XftFontDescription::XftDrawHandle
      |
      +--XftFontDescription::XftFontHandle

Package:

stx:libbasic

Category:

System-Support-External Memory

Version:

rev: 1.49 date: 2024/01/23 17:04:20

user: cg

file: ExternalAddress.st directory: libbasic

module: stx stc-classLibrary: libbasic

Description:

Instances of this class represent external (non-Smalltalk) memory addresses.
They are only useful to represent handles as returned by C functions,
or to pass them to C functions.
For example, Window- or WidgetIDs (which are actually 32 bit pointers) can be represented this way,
but better create a handle-subclass for it, to care for proper finalization.
(you should not use SmallIntegers for this, since they can only represent 31
 bits; LargeIntegers could be used in theory, but it is not a very good style
 to do so, since it makes things a bit cryptic - having ExternalAddresses
 around makes things pretty clear in inspectors etc.).

There is not much you can do with ExternalAddresses on the Smalltalk level;
creation/use should be done in primitive C-code via
   __MKEXTERNALADDRESS(voidPtr) and __ExternalAddressVal(obj).

ExternalAddresses are much like ExternalBytes - however, ExternalAddresses do not know
the size of the memory block and therefore do not allow you to access bytes via indexed at:/at:put: messages
(which ExternalBytes do).
ExternalAddresses are meant to remain anonymous, opaque handles.
Also, memory blocks which are freeable should be represented as ExternalBytes.

copyright
COPYRIGHT (c) 1995 by Claus Gittinger
             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:

 fromAddress: anInteger

 sizeInBytes

 newAddress: addr

return a new externalAddress (pointer), pointing to addr.

 newAddressFromBytes: bytesContainingAddress

return a new externalAddress (pointer), pointing to the addr contained in the argument.
The argument must be a byteArray-like object, whose first pointerSize bytes are extracted

Usage example(s):

|bytes ptr| bytes := ByteArray new:(ExternalAddress pointerSize). bytes pointerAt:1 put:16r12345678. ptr := ExternalAddress newAddressFromBytes:bytes. self assert:(ptr address = 16r12345678).

 null

return a new externalAddress (pointer), pointing to NULL.

 stderr

return the stderr FILE*

Usage example(s):

ExternalAddress stderr

 stdin

return the stdin FILE*

Usage example(s):

ExternalAddress stdin

 stdout

return the stdout FILE*

Usage example(s):

ExternalAddress stdout

 isBuiltInClass

return true if this class is known by the run-time-system.
Here, true is returned (but not for subclasses).

 pointerSize

Modified (comment): / 24-05-2021 / 21:22:55 / cg

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 sizeOfPointer

name confusion and also obsolete now -> see ExternalBytes

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 sizeofPointer

marked as obsolete by Stefan Vogel at 8-Aug-2022

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 uintSize

answer the size in bytes of an unsigned int.
obsolete now -> see ExternalBytes sizeofInt

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 ulongSize

answer the size in bytes of an unsigned long.
obsolete now -> see ExternalBytes

** This is an obsolete interface - do not use it (it may vanish in future versions) **

 ushortSize

answer the size in bytes of an unsigned short.
obsolete now -> see ExternalBytes

** This is an obsolete interface - do not use it (it may vanish in future versions) **

Instance protocol:

 beNull

 isNull

 address

return the start address as an integer

 instVarAt: index

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

 instVarAt: index put: newAddress

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

 = anExternalAddress

return true, if two externalAddress instance represent the same
C pointer

 hash

return a number useful for hashing

 asExternalAddress

convert to an ExternalAddress.
Useful to convert subclasses

Usage example(s):

(ExternalAddress newAddress:16r12345678) asExternalAddress

 asExternalBytes

return an ExternalBytes object pointing to where the receiver points to.
Use of this is not recommended; primitives which return externalAddresses
don't think that access to the memory is required/useful, while primitives
which do think so should return an externalBytes instance right away.

Usage example(s):

(ExternalAddress newAddress:16r12345678) asExternalBytes

 copyCStringFromHeap

fetch a 0-terminated string from my pointed-to address

 executor

will report an error when the next GC occurs...

(ExternalAddress newAddress:1) registerForFinalization

 finalizationLobby

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

 finalize

a previously registered external address was finalized.
Concrete subclasses should know what to do

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

 printOn: aStream

return a printed representation of the receiver

 setAddress: anInteger

set the address

 setAddressFromBytes: aByteArray

set the address from a pointer to which we have a pointer to

 isValid

true if I have an address

 isExternalAddress

(comment from inherited method)
return true if the receiver is some kind of externalAddress;
false is returned here - the method is only redefined in ExternalAddress.

Examples:

To pass some C-pointer from primitive code to smalltalk:

    ...
    RETURN (__MKEXTERNALADDRESS(foo));

pass it back to C and use it there:

    ...
    if (__isExternalAddress(anExternalAddress)) {
        ptr = __externalAddressVal(anExternalAddress));
    }
    ...

concrete example:

    test1
    %{
        static char foo[] = {'h', 'e' ,'l', 'l', 'o', ' ', 'w', 'o', 'r', 'l', 'd', '\n'};

        RETURN (__MKEXTERNALADDRESS(foo));
    %}

    test2:anExternalAddress
    %{
        if (__isExternalAddress(anExternalAddress)) {
            printf(__externalAddressVal(anExternalAddress));
            RETURN (self);
        }
    %}