eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ExternalAddress':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ExternalAddress


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:

Compatibility-V'Age
o  fromAddress: anInteger

o  sizeInBytes

instance creation
o  newAddress: addr
return a new externalAddress (pointer), pointing to addr.

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

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

o  stderr
return the stderr FILE*

Usage example(s):

     ExternalAddress stderr

o  stdin
return the stdin FILE*

Usage example(s):

     ExternalAddress stdin

o  stdout
return the stdout FILE*

Usage example(s):

     ExternalAddress stdout

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

o  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) **

o  sizeOfPointer
name confusion and also obsolete now -> see ExternalBytes

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

o  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) **

o  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) **

o  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) **

o  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:

Compatibility-Squeak
o  beNull

o  isNull

accessing
o  address
return the start address as an integer

o  instVarAt: index
redefined to suppress direct access to my address, which is a non-object

o  instVarAt: index put: newAddress
redefined to suppress direct access to my address, which is a non-object

comparing
o  = anExternalAddress
return true, if two externalAddress instance represent the same
C pointer

o  hash
return a number useful for hashing

converting
o  asExternalAddress
convert to an ExternalAddress.
Useful to convert subclasses

Usage example(s):

      (ExternalAddress newAddress:16r12345678) asExternalAddress

o  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

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

finalization
o  executor
will report an error when the next GC occurs...

(ExternalAddress newAddress:1) registerForFinalization

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

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

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

printing & storing
o  printOn: aStream
return a printed representation of the receiver

private-accessing
o  setAddress: anInteger
set the address

o  setAddressFromBytes: aByteArray
set the address from a pointer to which we have a pointer to

queries
o  isValid
true if I have an address

testing
o  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);
        }
    %}


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Sat, 15 Jun 2024 07:01:52 GMT