FFI: FFI-Kernel-mt.87.mcz

Marcel Taeumel uploaded a new version of FFI-Kernel to project FFI:
http://source.squeak.org/FFI/FFI-Kernel-mt.87.mcz

==================== Summary ====================

Name: FFI-Kernel-mt.87
Author: mt
Time: 2 June 2020, 8:12:39.748821 pm
UUID: 79a5b863-4682-dc47-9570-328e0cf5457a
Ancestors: FFI-Kernel-eem.86

Complements FFI-Pools-mt.18

=============== Diff against FFI-Kernel-eem.86 ===============

Item was changed:
  Object subclass: #FFIPlatformDescription
  instanceVariableNames: 'name osVersion subtype wordSize'
  classVariableNames: 'LastPlatform'
  poolDictionaries: ''
  category: 'FFI-Kernel'!
 
+ !FFIPlatformDescription commentStamp: 'mt 6/2/2020 15:18' prior: 0!
+ This class stores the information about the current (host) platform. It supports testing instances for platform compatibility and specificity. The entire FFI machinery should go through here, when making platform-specific decisions such as when figuring out the #wordSize for pointers to external memory (i.e., ExternalAddress class >> #new) or when looking up compatible definitions for external pools (i.e., ExternalPool class >> #compatibleResolvedDefinitions).
+
+
+ 1. DETECT PLATFORM CHANGE ON STARTUP
+
+ This class is registered for system startup. It then checks whether the current platform is different from the last one. In that case, a selection of FFI classes gets notified such as ExternalObject and ExternalType.
+
+
+ 2. PLATFORM SPECIFICITY
+
+ Platform descriptions may be unspecific, that is, some of their values may be undefined. For example, (FFIPlatformDescription name: 'unix') creates a valid description but is not specific about #osVersion or #wordSize. When comparing such descriptions, precedence of the platform values are:
+
+ platform name > osVersion > subtype > wordSize
+
+ So, if one description has a #name and the other does not, the first one is more specific. If both have #name but only the second one has #osVersion, the second one is more specific. If one has only #wordSize and another one has only #subtype, the second one is more specific because #subtype has a higher precedence than #wordSize.
+
+
+ 3. PLATFORM COMPATIBILITY
+
+ Platform descriptions implement a notion of compatibility, which is coupled to its notion of specificity as mentioned before. Using the same rules of precedence, compatibility is checked by comparing the description's values. If not specificed, compatibility is assumed. If specified, values must match via #= to be regarded compatible.
+
+ Here is an interesting edge case of two compatible platform descriptions:
+
+ | p1 p2 |
+ p1 := FFIPlatformDescription name: 'Win32' osVersion: '' subtype: 'IX86' wordSize: nil.
+ p2 := FFIPlatformDescription name: '' osVersion: 'linux-gnu' subtype: '' wordSize: 8.
+ p1 isCompatibleWith: p2.
+
+ Consequently, the developer has to be careful with unspecific platform descriptions, which are used, for example, in the definitions of external pools.
+
+
+ 4. FURTHER READING
+
+ - all references to FFIPlatformDescription
+ - all senders of #wordSize
+ - class comments of ExternalAddress, ExternalType, ExternalPool, ExternalObject
+ !
- !FFIPlatformDescription commentStamp: 'monty 4/1/2018 12:02' prior: 0!
- This class stores the platform information for an FFIExternalSharedPool and supports testing instances for platform compatibility and specificity.!

Item was added:
+ ----- Method: FFIPlatformDescription class>>cleanUp: (in category 'initialize-release') -----
+ cleanUp: aggressive
+
+ aggressive ifTrue: [
+ "Force a detection of platform change on next system start up."
+ LastPlatform := nil].!

Item was changed:
  ----- Method: FFIPlatformDescription class>>startUp: (in category 'system startup') -----
  startUp: resuming
  "Notify all FFI classes about platform changes."
 
  resuming ifTrue: [
  LastPlatform in: [:lastPlatform | self newCurrent in: [:currentPlatform |
  lastPlatform = currentPlatform
  ifTrue: [
  self flag: #discuss. "mt: Maybe add #platformResuming?"
  ExternalAddress allBeNull]
  ifFalse: [
  LastPlatform := currentPlatform. "Update now. See #current."
+ { ExternalType. ExternalAddress. ExternalObject. ExternalPool }
- { ExternalType. ExternalAddress. ExternalObject. FFIExternalSharedPool }
  do: [:cls | cls
  platformChangedFrom: lastPlatform
  to: currentPlatform] ]]] ].!