|
Class: ExternalAddress
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
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.
ByteArray
ExternalBytes
ExternalFunction
[how to write primitive code]
Compatibility-V'Age
-
fromAddress: anInteger
-
-
sizeInBytes
-
instance creation
-
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
queries
-
isBuiltInClass
-
return true if this class is known by the run-time-system.
Here, true is returned (but not for subclasses).
-
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):
-
sizeOfPointer
-
obsolete now -> see ExternalBytes
usage example(s):
-
uintSize
-
answer the size in bytes of an unsigned int.
obsolete now -> see ExternalBytes
usage example(s):
-
ulongSize
-
answer the size in bytes of an unsigned long.
obsolete now -> see ExternalBytes
usage example(s):
-
ushortSize
-
answer the size in bytes of an unsigned short.
obsolete now -> see ExternalBytes
usage example(s):
Compatibility-Squeak
-
beNull
-
-
isNull
-
accessing
-
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
comparing
-
= anExternalAddress
-
return true, if two externalAddress instance represent the same
C pointer
-
hash
-
return a number useful for hashing
converting
-
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
printing & storing
-
printOn: aStream
-
return a printed representation of the receiver
private-accessing
-
setAddress: anInteger
-
set the address
-
setAddressFromBytes: aByteArray
-
set the address from a pointer to which we have a pointer to
queries
-
isValid
-
true if I have an address
testing
-
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.
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);
}
%}
|