A threading model tells the C SDK which thread to use to service registered polled functions. The threading model can affect the performance of your client application. If your application performs multiple tasks, such as data acquisition and file transfers, it is strongly recommended that you choose the multi-threading model. The supported threading models are described in the following table:

To set the threading model use the twOnPolled(char* entityName) function.

The next two sections explain how to configure the multi-threaded model and the tasker model.

To tell the SDK to use the multi-threaded SDK model, set TW_THREADING_MULTI to 2. To pass control of polling of any registered polled functions to a given thread, call the twOnPolled function. This function does not exit until the application is terminated.

The built-in tasker is a simple round-robin execution engine that calls all registered functions at a rate defined when those functions are registered. If using a multitasking or multi-threaded environment you may want to disable the tasker and use the native environment. If you choose to disable the tasker, you must call twApi_TaskerFunction() and twMessageHandler_msgHandlerTask() on a regular basis (every 5 milliseconds or so). Comment out the #define statement for this setting if you are using your own threads to drive the API, as you do not want the tasker to run in parallel with another thread that runs the API.

To properly initialize the Tasker, you must define ENABLE_TASKER:

The Windows-based operating systems have a tick resolution (15ms) that is higher than the tick resolutions requested by the C SDK (5ms). For information about achieving the best performance on a Windows-based operating system, refer to Running on a Windows-based Operating System

To execute all registered polled functions for any Thing Template or Thing Shape, call the twExtPerformPolledFunctions() function. This handler function can be called directly or by the tasker.

The C SDK has full support for all the remote directory/file browsing capabilities of ThingWorx platform as well as bidirectional file transfer. To use this functionality, define ENABLE_FILE_XFER. This module will add ~15KB of code space to your application, so severely constrained environments may want to omit this functionality.

Before you try to transfer a file, you must start all your threads. The function twExt_Start(500, TW_THREADING_MULTI,5); starts all your threads and returns. Once it returns, call twMessageHandler_msgHandlerTask(now,NULL):. Then it is safe to do the file transfers.

The C SDK uses WebSocket compression (zlib) for all WebSocket communications, including file transfers, by default. In general, leaving compression turned on reduces bandwidth used by the edge application, but requires more memory and CPU usage. Choose whether to leave compression enabled, based on the capabilities of your devices and on the available bandwidth. If you need to disable compression, use the twApi_DisableWebSocketCompression() function. This function is in the twApi.c file, which is located in the ./src/api/directory of your C SDK installation. It is described in the twApi.h file, which is located in the ./src/api/ directory. To call the function, add it to your code after you initialize the API by calling twApi_Initialize() and where you configure the API. For example:

This example sets up an offline message store location and disables compression. When the messages that were stored while the device was offline are eventually transmitted, the messages use more memory and CPU. Disabling compression is useful if you have a limited bandwidth or want to keep bandwidth costs down.

For configuration recommendations for optimal performance of large file transfers, refer to Best Practices for Transferring Large Files.

idle_time_before_ping allows users to delay sending WebSocket pings to the Thingworx Platform in situations where the connection is either too congested with data, such as during file transfers, or when the platform is too congested to respond promptly. Normally, this setting is configured to 0 milliseconds, which allows pings to be sent to the platform on the schedule dictated by ping_rate.

When idle_time_before_ping is set to a non-zero value in milliseconds, the normal ping rate timer will be delayed until the inbound message channel has been quiet for the specified idle_time_before_ping duration.

This setting should only be used in situations where the logs indicate that the client is disconnecting due to missed ping responses during periods of high traffic from Thingworx Platform to the client. The recommended initial value for this configuration is 500 milliseconds.

The C SDK has full support for application tunneling. Application tunnels allow for secure, firewall transparent tunneling of TCP client server applications such as VNC and SSH. To use this functionality, you must define ENABLE_TUNNELING. This module adds ~5KB of code space to your application, and upwards of 100KB RAM, depending on usage, so severely constrained environments may want to omit this functionality.

The Windows-based operating systems have a tick resolution (15ms) that is higher than the tick resolutions requested by the C SDK (5ms). For information about achieving the best performance for tunneling in a Windows-based operating system, refer to Running on a Windows-based Operating System.

The C SDK has several settings that you can modify, based on the needs of your application. For example, your devices may require minimizing RAM usage, or you want to improve performance. You can find the defaults for these settings in the file src/config/twDefaultSettings.h. In most cases you do not need to change these settings. If you must change them, exercise caution when making the changes. With the exception of TW_MAX_TASKS, all settings can be modified at runtime by changing the appropriate setting in the global twcfg structure. The structure definition can be found in src/config/twDefaultSettings.h.