| |
Using Parasolid |
| <<< Parasolid Release Area | Chapters | Environment >>> |
pskernel.dll
) created from the object file library. An executable program can be made by linking the object files of a main program, your frustrum, the Parasolid ‘interface library’,
pskernel.lib
in the
dll
directory.
pskernel_archive.lib
). An executable program can be made by linking the object files of a main program, your frustrum, and the Parasolid library.
libpskernel_archive.a
). This can be linked into an Xcode project that builds an iOS app, which must supply a frustrum.
Function headers for the functions available in the full Parasolid kernel can be found in the file
parasolid_kernel.h
.
In order to use the supplied DLL, your application must register a frustrum - see Chapter 5, “Registering the Frustrum” in the Downward Interfaces manual for further details. See Chapter 6, “Environment”, in this manual, for more details on building and linking Parasolid.
The file
parasolid_link.com
, or
parasolid_link.bat
on Windows platforms, shows examples of linking or binding Parasolid.
When transmitting part files using an explicit (non-default) transmit version, the schema file is written to the schema directory of your Parasolid installation if it is not already present.
In a Windows application, your frustrum could typically look for schema files in one of two ways:
The dummy frustrum uses an environment variable called P_SCHEMA. Your finished application should not use the dummy frustrum.
When writing simple Parasolid programs, you may wish to initially use the dummy frustrum provided. While this frustrum works, it is not complete, and is only provided as an outline to help you develop your own frustrum. The notes in the source file
frustrum.c
provide more guidance.
The command files
frustrum_library.com
on UNIX platforms. or
frustrum_library.bat
on Windows platforms, will create a dummy frustrum library from the ‘C’ file, although this library is provided with the release.
If you wish to use the dummy frustrum, then you must either set the environment variable P_SCHEMA, to the full pathname of the schema directory or you must modify the code in the dummy frustrum so that the schema directory is specified explicitly, and P_SCHEMA is not used. If you use P_SCHEMA, you must make sure it is set every time you log in.
As noted above, the location of schemas is an app design decision on iOS.
|
Note: Running KID on Android requires some knowledge of the ADB tool, and the interactive ADB shell environment, Running KID is not necessary for app development using an IDE. |
In order to run KID, you need to setup some environment variables:
If your application uses the dummy frustrum, then you may have already specified P_SCHEMA.
The environment variables can be set up as follows:
$ PARASOLID="base directory pathname"
$ P_LISP="full LISP directory pathname"
$ P_SCHEMA="full SCHEMA directory pathname"
$ export PARASOLID P_LISP P_SCHEMA
$ setenv PARASOLID "base directory pathname"
$ setenv P_LISP "full LISP directory pathname"
$ setenv P_SCHEMA "full schema directory pathname"
You need to make sure these commands are executed before you run KID: you could add the statements shown above to a script, perhaps run from your login script. You should specify full path names so that KID can be run from any directory location.
The environment variables can be set up in a Command Prompt as follows:
set PARASOLID=base directory pathname
set P_LISP=full LISPDATA directory pathname
set P_SCHEMA=full schema directory pathname
You should set up these environment variables as part of your Windows login account, and you should specify full path names so that Parasolid can be run from any folder location.
The environment variables can be set up in the ADB shell environment in the same way as for the Bourne shell on UNIX.
KID is supplied as an executable file and can be invoked as described below
Type the following at a UNIX prompt:
$ $PARASOLID/shared_object/kid.exe
You should ensure you have set the library search environment variable appropriately. See Section 4.2.4, “Finding shared libraries”. When executed, KID will attempt to load the file
$P_LISP/bbcini.lsp
.
If you installed Parasolid using the installer provided (see Section 3.2.1), and you have set up the environment variables in your account, you can run KID by double-clicking
kid.exe
inside either the
intel_nt\base\dll
folder or the
x64_win\base\dll
folder (as appropriate) in your installation directory.
You will need to use the ADB tool to transfer files to your device. This must be to a directory where you have write and execute permissions, and you will need to run KID from a directory where you have write permission, since it creates journal files by default. The directory
/data/local/tmp
is suitable for both of these purposes, and you can create sub-directories of it if you wish.
Use
adb push
to transfer the contents of the shared_object directory, the
lispdata
directory and the
schema
directory to your device. Start the shell environment with
adb shell
, use
cd
to move to a directory where you have write permission, set the environment variables, and run
kid.exe
.
This section provides a quick guide to initializing KID’s graphics facilities. For more information, see the KID Manual.
KID graphics uses the X Windows system. Make sure that X is running before starting KID, then before using any other graphics commands, type one of the following at the LISP prompt:
> (graphics open_device ´x) > (graphics open_device ´xcolour) |
To use KID graphics on Intel MacOS, you need to install and start the X11 server. This can be found under Applications > Utilities > X11 on any Intel MacOS system.
KID graphics uses Microsoft Windows GDI functions. Monochrome and color windows are available as alternatives, by typing either of the following at the LISP prompt:
> (graphics open_device ´nt) > (graphics open_device ´ntcolour) |
KID graphics are not available on these platforms.
If no graphics are required, use:
> (graphics open_device ’null) |
This will allow you to call Parasolid rendering functions without getting graphics output (for example, for testing purposes
You can ensure KID graphics are set up correctly using
> (graphics enquire) |
Executing Parasolid code requires enough stack space: at least 1MB for 32-bit platforms, and 2MB for 64-bit platforms. There are currently two platforms where the default stack size for the program's first thread is too small, and several platforms where the default stack size for additional threads (which can be different) is too small. The latter applies both to application threads that call Parasolid, and to threads that Parasolid creates internally for its SMP functionality.
|
Note: A thread's stack size cannot be changed once the thread exists: it is fixed when the thread is created. |
For these platforms, use the following option to set the minimum default stack size:
. A larger stack size (the first value) will be required if your application uses significant amounts of stack space itself.
/stack:2097152,131072
You can do this with either
link.exe
, when linking your executable file(s), or
editbin.exe
, to modify them after linking. Note that this is required for all 64-bit Windows programs that use Parasolid, even if they do not use multiple application threads or Parasolid SMP threads.
The default thread stack sizes for each platform are shown in the table below. Sizes marked with * are too small by default, so any Parasolid-based application must change them.
For X64 WIN and ARM WIN, we recommend that you use the
/stack
option documented above to change the default stack size for all threads, including application threads.
For UNIX, Android and iOS platforms where the stack size is too small, use
pthread_attr_setstacksize
to set a stack size attribute in the
pthread_attr_t
structure that you pass to
pthread_create
when creating your application threads.
For iOS, we recommend that you should not call Parasolid from the first thread of your app. Some Parasolid calls can take enough time to cause iOS to decide that the app has become unresponsive, and kill it. Create a thread with an appropriate size stack and use that to call Parasolid.
For Android, you should likewise not call Parasolid from the UI thread of your app. As for iOS, Parasolid calls can take enough time to cause Android to decide that the app has become unresponsive, and display an “Application Not Responding” message. Create a thread with an appropriate size stack and use that to call Parasolid.
Calling PK_SESSION_set_smp_stacksize has no effect on application threads: that PK function only affects the stack sizes of threads created by Parasolid.
Call PK_SESSION_set_smp_stacksize before turning on Parasolid SMP. For example:
size_t new_stk = 256 * 1024 * sizeof(char*); /* 384, not 256, on iOS */ PK_SESSION_smp_o_t opt; PK_SESSION_smp_o_m( opt ); /* Set SMP parameters in opt */ PK_SESSION_set_smp_stacksize( new_stk ); PK_SESSION_set_smp( &opt ); |
Parasolid has been adapted for Symmetric Multi-Processing (or parallel processing) via the multi-threading environments supported under Windows and the Posix threads model on UNIX. The following platforms support SMP at this release:
There are several issues that need to be considered when deciding how many threads you should use, some of which are platform-dependent.
Parasolid is thread-safe and can be called from multiple threads in the same application. The Parasolid PK and KI APIs manage multiple application threads to ensure safety. See Section 113.2, “How to set up and use application threads”, in the Parasolid Functional Description for details. Parasolid can also create and use “worker” threads internally, to improve performance. This is described in Chapter 114, “Symmetric Multi-Processing In Parasolid”, in the Functional Description, with more details below.
For many Parasolid functions, the thread that enters Parasolid from the calling application does all the work. For functions that use SMP, the caller’s thread does preparatory work, and then sets Parasolid SMP “worker” threads to work. Those threads are created by Parasolid, and perform most of the work of functions that use SMP. The caller’s thread waits for the worker threads to finish, collects their results, and returns to the application. The number of these worker threads is set by PK_SESSION_set_smp. That is the maximum number of such threads that Parasolid will ever be using at one time. Application threads are not included in this number.
The Parasolid functions that use SMP are functions that perform jobs that can be decomposed into many smaller and independent tasks. For example, mass properties such as surface area are calculated by integrating over all the faces of a body. The faces are independent, so separate threads can handle them easily. A side effect of this design is that the worker threads all do similar kinds of calculations. Their performance is limited by the speed of the computer’s processors and their memory subsystems; the speed of other parts of the computer has little effect.
If Parasolid SMP cannot create internal worker threads, it carries out the work they would have performed in the thread used to call Parasolid. This means that Parasolid continues to operate correctly (though possibly less quickly) if the operating system is unable to create worker threads when Parasolid needs them. Parasolid reports this situation through the Parasolid report mechanism. If worker threads subsequently can be created again, they will be used. This is also reported via the Parasolid report mechanism.
There is a limit on the number of threads that Parasolid can use, noted in the documentation of PK_SESSION_smp_o_t.
Symmetrical multi-core processors, with two or more complete and identical physical processors in one package, work very well with Parasolid SMP.
Asymmetrical multi-core processors, such as the Apple M1, used in the first generation of ARM MacOS systems, have a mixture of types of processors. The usual configuration is a mix of high-performance and power-efficient cores, to enable performance to be traded off against battery life. You may need to limit the number of Parasolid SMP worker threads to the number of high-performance cores, but experimentation and benchmarking with your application’s usage of SMP is advisable.
SMT describes a particular style of processor design. This is useful for some kinds of applications, but not - so far - for Parasolid. The best-known SMT system is Intel’s HyperThreading. This shares the execution units of a single processor between two “logical processors”. Both of these are visible to the operating system, and can be given work to do, but the threads they run only get a share of the processor’s power, rather than the full use of a processor. This makes SMT most useful for applications that need a large number of threads but where the threads don’t have to do a lot of calculations. Web serving, file/print serving and similar tasks often benefit from SMT.
HyperThreading isn’t very beneficial to Parasolid, although they work together correctly. Some Parasolid operations can run faster by using the extra threads that HyperThreading provides, but others run slower, and the overall effect is usually a small loss, on “NetBurst” architecture processors, or no benefit with the improved HyperThreading of the Core i-series processors. Parasolid worker threads are limited by processor power, and HyperThreading doesn’t provide more of that; it only provides a different way of accessing the existing power. Parasolid SMP threads also tend to be doing similar work, and thus competing for the same execution units.
For best Parasolid performance on old NetBurst processors, turn off SMT. For Core i-series and later processors, there is no need to do this.
We do not recommend that Parasolid-based applications should try to programmatically associate themselves with particular processors in an SMP system. If two or more programs try to do such things simultaneously, the usual result is worse performance.
ARM WIN is a special case. The usual processors for this platform are asymmetric. This works well in interactive usage, but causes problems in Parasolid’s automated testing. For reasons that are not yet clear to us, if an ARM WIN device has been running test code with no user interface for several days, it tends to run everything on its slow cores, dramatically slowing down testing. We suggest that any automated testing systems you create for applications that run on ARM WIN should use processor affinity to ensure that they run on the fast cores. This solved our problems with Parasolid testing. An example program,
probe_affinity.c
, is supplied with the Parasolid Jumpstart Kit. This examines a Windows computer to discover if any of the cores are significantly faster, and provides examples of setting affinity. We suggest that you experiment with processor affinity in your application(s); we do not yet know enough to recommend that you should, or should not, use it in interactive applications.
For applications that are the main work of the computer running them, such as interactive CAD on a desktop machine, use as many threads as there are available physical processors, since response time to the user is of primary importance.
For applications such as translators, which may form a small part of the workload of a server, consider the issue more carefully. Parasolid doesn’t run twice as fast with two threads, so the overall throughput of a heavily loaded server may decrease if you use Parasolid SMP. However, if a server with many processors isn’t heavily loaded, using Parasolid SMP can be beneficial. For server applications, it is wise to make the use of SMP something that can be configured, rather then being decided automatically by the program.
There is a wide variety of SMP and SMT hardware that can be used for these platforms. Microsoft Windows provides an API, GetLogicalProcessorInformation, which can be used to identify some of the processor facilities of a computer running Windows, and is recommended for use with Parasolid.
Use this API to find out the number of processor cores available. If this is greater than 1, use that number of threads, to a maximum of the Parasolid limit, with the PK_thread_absolute_c thread format.
This method avoids using a thread per logical processor on machines with HyperThreading active.
This platform can use most of the types of hardware that are available for Microsoft Windows platforms.
To discover the processor configuration, first use
sysconf(_SC_NPROCESSORS_ONLN)
to get the number of processors. If this is greater than 1, read and parse the text file
/proc/cpuinfo
. If the processor entries in that file contain “core id” values, then count the number of different “core id” values (they are not always consecutive numbers), to find out how many processor cores exist. With no “core id” values, you have a machine with single-core processors, so count the number of “physical id” values to get the number of processor cores. If there is more than 1 processor core, use that number of threads, to a maximum of the Parasolid limit, with the PK_thread_absolute_c thread format.
This method avoids using a thread per logical processor on machines with HyperThreading active. The best Parasolid performance on machines that support HyperThreading is obtained by turning off HyperThreading in the machine’s BIOS.
Use
sysconf(_SC_NPROCESSORS_ONLN)
to get the number of processors. If this is greater than 1, enable SMP with the default option of 1 thread per processor, and Parasolid will apply its own limit.
Use
sysctl()
with
CTL_HW
and
HW_AVAILCPU
to get the number of available processors. If this is greater than 1, enable SMP with the default options of 1 thread per processor; Parasolid will apply its own limit.
Parasolid uses OS-level locking with POSIX threads, since the OS-level locks have much lower overheads than Apple’s pthreads mutexes. Parasolid sets the Quality of Service class for threads that it creates to
QOS_CLASS_USER_INITIATED
, using the function
pthread_attr_set_qos_class_np()
. This assists the macOS scheduler in prioritising threads.
All processors used for this platform are asymmetric. Parasolid SMP works much better when it is limited to a number of threads less than or equal to the number of fast processor cores in the machine. You can establish this number as follows:
sysctlbyname()
with the argument
¨hw.perflevel0.logicalcpu¨
. See “man sysctlbyname” for more details.
Parasolid uses OS-level locking with POSIX threads, since the OS-level locks have much lower overheads than Apple’s pthreads mutexes. Parasolid sets the Quality of Service class for threads that it creates to
QOS_CLASS_USER_INITIATED
, using the function
pthread_attr_set_qos_class_np()
. This assists the macOS scheduler in prioritising threads.
Please note that when you use Parasolid SMP, Parasolid may call any of its downward interfaces from its SMP “worker” threads. This allows SMP threads to work without having to coordinate with the master thread, which improves performance. Similarly, if your application calls Parasolid from multiple threads, then the downward interfaces may be called from any of those threads. For these reasons, the functions you provide for downward interfaces must not make assumptions about which threads will call them, or in which order.
By default, Parasolid will only make one downward interface call at a time, avoiding the need for your functions to be fully thread-safe. If your frustrum is thread-safe, you can allow Parasolid to make multiple simultaneous calls to GO functions with the ‘go_thread_safe’ option to PK_SESSION_register_fru_2. Other exceptions to the single-call rule are noted in the documentation for individual functions. For more details, see Chapter 113, “Calling Parasolid From Multiple Threads” and Chapter 114, “Symmetric Multi-Processing In Parasolid” in the Functional Description.
The situations where thread safety in your frustrum is important include:
On platforms where the operating system doesn't do this automatically, Parasolid copies the floating-point trap settings in use by your application into its SMP “worker” threads. See Section 6.4, “Floating-point information”, for details of floating-point traps on Parasolid platforms.
On UNIX platforms, code run by SMP “worker” threads generates run-time errors in the same way as code run by the thread you use to call Parasolid. Your application’s signal handler should be prepared to deal with this situation.
On Microsoft Windows platforms, Parasolid’s thread management catches run-time errors in worker threads and re-creates them in the thread that you used to call Parasolid. This allows you to use either signals or Structured Exception Handling to handle run-time errors.
| <<< Parasolid Release Area | Chapters | Environment >>> |