4. Changes in the GCI Interfaces
This chapter describes changes and updated information related to the GemBuilder for C and FFI interfaces, including:
4.1 GCI changes
GciDirtyTrackedObjs functionality removed
The Dirty Tracked Objects set is no longer needed, and has been removed.
Removed GCI calls
GciDirtyTrackedObjs
GciReleaseAllTrackedOops
GciReleaseTrackedOops
GciSaveAndTrackObjs
GciTrackedObjsFetchAllDirty
GciTrackedObjsInit
GCI_JIS_CHAR_TO_OOP
GCI_OOP_TO_JIS_CHAR
Added Lz4 compression functions
GciCompressUsingLz4
(int) GciCompressUsingLz4(
const char* src,
char* dst,
int srcSize,
int dstCapacity );
Wrapper for the lz4 function LZ4_compress_default().
Compress srcSize bytes from buffer src into already allocated dst buffer of size dstCapacity. Compression is faster, and guaranteed to succeed, if dstCapacity >= LZ4_compressBound(srcSize).
If the function cannot compress src into a more limited dst buffer size, compression stops, function result is zero, and dst content is undefined (invalid).
GciUncompressUsingLz4
(int) GciUncompressUsingLz4(
const char* src,
char* dst,
int compressedSize,
int dstCapacity );
Wrapper for LZ4_decompress_safe().
Decompress the compressed string at *src and place the result in *dst. *dst must be already allocated. The exact size of the compressed string at *src, and the maximum size for the destination must be provided; if dstCapacity is insufficient, decompression stops and the functions returns a negative result.
Added variants of existing functions
One-time login support
The new feature to allow a one-time login password to be created (described starting here) can be used in GemBuilder for C, by specifying the new flag GCI_ONETIME_PASSWORD (0x400) with the loginFlags in the argument for GciLoginEx() or GciLoginEx_().
Configuration file handling support
v3.7 includes additional options and finer control over where and how GemStone executable and system configuration files are handled; this is described starting here.
Support for this in GBC is provided by GciInit_, which is a variation of GciInit that includes additional arguments, and the new class GciCfgFileArgs.
GciInit_
(int) GciInit_(
BoolType quietMode,
GciProcessType gciProcessType,
GciCfgFileArgs *gciCfgFileArgs,
char *configFileWarn,
size_t warnSize);
A variant of GciInit, with additional arguments to support new configuration file semantics. Only one of GciInit/GciInit_ should be used.
*gciCfgFileArgs is the results of parsing command line arguments for configuration files; see the definition for GciCfgFileArgs in gci.ht. gciProcessType should be GCI_PROCESS_GEM in linked customer applications; GciProcessType is defined in gci.ht.
This function returns 0 for success, -1 for errors in the configuration file, and -2 for memory allocation errors in libgcilnk.
4.2 GCI thread-safe changes
The thread-safe GCI is provided in gcits.hf.
Added Thread-safe functions
GciTsDebugConnectToGem
(GciSession) GciTsDebugConnectToGem(
int gemPid,
GciErrSType *anEerr );
Connect to a gem's listening debug port on localhost; only supported for gems running on the same node. See the GEM_LISTEN_FOR_DEBUG configuration parameter and DEBUGGEM topaz command. The gemPid argument to GcitsDebugConnectToGem is the first arg to topaz DEBUGGEM. A call to GciTsDebugConnectToGem must be followed by a call to GciTsDebugStartDebugService.
GciTsDebugStartDebugService
(BoolType) GciTsDebugStartDebugService(
GciSession aSession,
uint64 debugToken,
GciErrSType *anErr );
This function must be preceded by GciTsDebugConnectToGem which creates a GciSession. Using this session, GciTsDebugStartDebugService will validate the debugToken argument and interrupt any Smalltalk execution in progress in the target gem by the equivalent of GciTsBreak(aSession, FALSE, &anErr). debugToken is the second arg to topaz DEBUGGEM. To terminate the debug session, and assumming the session being debugged was waiting in System class >> waitForDebug, the client should execute System cancelWaitForDebug or System _cancelWaitForDebugExitClient, and then call GciTsLogout.
GciTsNbPoll
(int) GciTsNbPoll(
GciSession session,
int timeoutMs,
GciErrSType *gciErr );
1 - result or error is ready, call GciTsNbResult to get the result or error.
-1 - error, (invalid session, no NB call in progress, peer disconnected), details will be in gciErr.
0 - do not block, return immediately
-1 - block forever until the Nb call finishes or an error occurs.
> 0 block for up to timeoutMs ms before returning the result
4.3 Foreign Function Interface (FFI) related changes
errno: unsafe; use alternate methods to access to CCallout errno
Since CCallout class methods errno and errno: access a value stored in the GsProcess, there is a risk of that two FFI calls (within a single GsProcess) may access this, and set/retrieve incorrect values. (#49432)
The methods errno and errno: now signal an error and should not be used. You may still used callWith: if you do not need access to the errno information.
The method CCallout >> callWith:errno:, which was added in v3.6.4, can be used when the errno information is needed. See the method image comments for details.
Generated library code such as GciLibrary methods now invoke callWith:errno: rather than callWith:.
4.4 Updated Compile and Link Information
Linux Compile and Link Information
Complier version
Red Hat Linux ES 9.2: gcc/g++ 11.3.1
Red Hat Linux ES 8.7: gcc/g++ 8.5.0
Red Hat Linux ES 7.9: gcc/g++ 4.8.5
Compiling a user action or GCI application
g++ -fmessage-length=0 -fcheck-new -O3 -ggdb -m64 -pipe
-D_REENTRANT -D_GNU_SOURCE -pthread -fPIC -fno-strict-aliasing
-fno-exceptions -I$GEMSTONE/include -x c++ -c userCode.c
-o userCode.o
The following warn flags are recommended for compilation:
-Wformat -Wtrigraphs -Wcomment -Wno-aggregate-return -Wswitch
-Wshadow -Wunused-value -Wunused-variable -Wunused-label
-Wno-unused-function -Wchar-subscripts -Wmissing-braces
-Wmissing-declarations -Wmultichar -Wparentheses -Wsign-compare
-Wsign-promo -Wwrite-strings -Wreturn-type
-Wno-format-truncation -Wuninitialized
AIX Compile and Link Information
Compiling a user action or GCI application
xlC_r -O3 -qstrict -qalias=noansi -q64 -+ -qpic
-qthreaded -qarch=pwr6 -qtune=balanced -D_LARGEFILE64_SOURCE
-DFLG_AIX_VERSION=version -D_REENTRANT -D_THREAD_SAFE
-qminimaltoc -qlist=offset -qmaxmem=-1 -qsuppress=1500-010:1500
-029:1540-1103:1540-2907:1540-0804:1540-1281:1540-1090:1540-2988
-qnoeh -I$GEMSTONE/include -c userCode.c -o userCode.o
Depending on your version of AIX, you need to include -DFLG_AIX_VERSION=71 or -DFLG_AIX_VERSION=72.
Also note that there is no space in the -qsuppress arguments that are continued on the following line.
DARWIN Compile and Link Information
Complier version
Ventura: Apple clang version 14.0.3 (clang-1403.0.22.14.1)
Compiling a user action or GCI application
g++ -fmessage-length=0 -O3 -ggdb -m64 -pipe -fPIC
-fno-strict-aliasing -D_LARGEFILE64_SOURCE -D_XOPEN_SOURCE
-D_REENTRANT -D_GNU_SOURCE -I$GEMSTONE/include -x c++
-c userCode.c -o userCode.o
The following warn flags are recommended for compilation:
-Wno-format -Wtrigraphs -Wcomment -Wsystem-headers -Wtrigraphs
-Wno-aggregate-return -Wswitch -Wshadow -Wunused-value
-Wunused-variable -Wunused-label -Wno-unused-function
-Wchar-subscripts -Wno-conversion -Wmissing-braces -Wmultichar
-Wparentheses -Wsign-compare -Wsign-promo -Wwrite-strings
-Wreturn-type -Wno-nullability-completeness
-Wno-expansion-to-defined
Windows Compile and Link Information
Complier/Debugger version
Microsoft Visual Studio Professional 2019 Version 16.11.24
VisualStudio.16.Release/16.11.24+33328.57
Microsoft .NET Framework Version 4.8.09032
Visual C++ 2019 00435-60000-00000-AA889
Compiling a GCI application
cl /W3 /Zi /MD /O2 /Oy- -DNDEBUG /TP /nologo /D_LP64 /D_AMD64_
/D_CONSOLE /D_DLL /DWIN32_LEAN_AND_MEAN
/D_CRT_SECURE_NO_WARNINGS /EHsc -volatile:iso
/DNATIVE /I 'VisualStudioInstallPath\include'
/I 'VisualStudioInstallPath\Tools\MSVC\14.29.30133\atlmfc\include'
/I 'VisualStudioInstallPath\Tools\MSVC\14.29.30133\include'
/I '%GEMSTONE%include' /c 'userCode.c' -FouserCode.obj
-FduserCode.pdb
Linking a GCI application
link /LIBPATH:VisualStudioInstallPath\Tools\MSVC\14.29.30133\lib\x64
/LIBPATH:VisualStudioInstallPath\Tools\MSVC\14.29.30133\atlmfc\lib\x64
/LIBPATH:WindowsKitsInstallPath\10\lib\10.0.18362.0\um\x64
/LIBPATH:WindowsKitsInstallPath\10\lib\10.0.18362.0\ucrt\x64
/DEBUG /RELEASE /OPT:REF /INCREMENTAL:NO /MAP /nologo
/MANIFEST /MANIFESTFILE:userAppl.exe.manifest
/MANIFESTUAC:level='asInvoker' /FORCE:MULTIPLE userCode.obj
%GEMSTONE%lib\gcirtlobj.obj %GEMSTONE%lib\gcirpc.lib ws2_32.lib
netapi32.lib advapi32.lib comdlg32.lib user32.lib gdi32.lib
kernel32.lib winspool.lib Secur32.lib Dbghelp.lib
/NODEFAULTLIB:libcmt.lib /out:userAppl.exe