eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ExternalAddress':

Home

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

Class: ExternalAddress


Inheritance:

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

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.42 date: 2019/04/11 08:50:39
user: cg
file: ExternalAddress.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

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.


Related information:

    ByteArray
    ExternalBytes
    ExternalFunction
    [how to write primitive code]

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

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
answer the size in bytes of a pointer.
Notice: this is inlined by the compiler(s) as a constant,
therefore, queries like
'ExternalAddress pointerSize == 8'
cost nothing; they are compiled in as a constant
(and even conditionals are eliminated).

obsolete now -> see ExternalBytes

usage example(s):

     self pointerSize

o  sizeOfPointer
obsolete now -> see ExternalBytes

usage example(s):

     self sizeOfPointer

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

usage example(s):

     self uintSize

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

usage example(s):

     self ulongSize

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

usage example(s):

     self ushortSize


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

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.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 06:39:17 GMT