ThingWorx C SDK
Classes | Typedefs | Enumerations | Functions
twThreadUtils.h File Reference

Provides simple thread management for ThingWorx C SDK functionality. More...

#include "twOSPort.h"
#include "twMap.h"

Go to the source code of this file.

Classes

struct  twPolledFunctionRecord
 

Typedefs

typedef void(* twOnPolled) (char *entityName)
 
typedef struct twPolledFunctionRecord twPolledFunctionListRecord
 

Enumerations

enum  twThreadingModel { TW_THREADING_SINGLE =0, TW_THREADING_TASKER =1, TW_THREADING_MULTI =2 }
 

Functions

void twExt_RegisterPolledTemplateFunction (twOnPolled polledFunction, char *templateName)
 
void twExt_RegisterPolledShapeFunction (twOnPolled polledFunction, char *shapeName)
 
void twExt_RemovePolledFunction (twOnPolled polledFunction)
 
void twExt_PerformPolledFunctions (DATETIME now, void *params)
 
void twExt_Idle (uint32_t intervalMsec, enum twThreadingModel threadingModel, uint32_t messageHandlerThreadCount)
 
void twExt_Start (uint32_t dataCollectionRate, enum twThreadingModel threadingModel, uint32_t messageHandlerThreadCount)
 
int twExt_Stop ()
 
int twExt_WaitUntilFirstSynchronization (uint32_t timeoutMills)
 

Detailed Description

Provides simple thread management for ThingWorx C SDK functionality.

Author
bill..nosp@m.reic.nosp@m.hardt.nosp@m.@thi.nosp@m.ngwor.nosp@m.x.co.nosp@m.m

This module introduces two thread management functions, twExt_Idle() and twExt_Start(). Both functions can be called to establish the minimum number of support threads and services to manage an Always-On connection to ThingWorx. The main difference is that twExt_Idle() will not return until your application is terminated. Any thread used to call this function will not exit. twExt_Idle() is useful in situations where your application only wants to start up services and then idle until it is exited.

twExt_Start() assumes that you are starting up Always-On services as part of your application's normal start up process and need the calling thread to return once this is done to continue with operations you may need to perform as part of you startup process.

Both functions set up periodic calls to any polled functions you declare which will be bound to specific Thing Shapes or Thing Templates. Periodic polled functions, often referred to as "Process Scan Request" functions can be declared against any Edge Thing Shape or Template using the twExt_RegisterPolledTemplateFunction() and twExt_RegisterPolledShapeFunction() functions can can be used to generate simulated data or to poll hardware for new data in your Thing or Shape.

Function Documentation

void twExt_Idle ( uint32_t  intervalMsec,
enum twThreadingModel  threadingModel,
uint32_t  messageHandlerThreadCount 
)

Call this function if you want this thread to take control of polling any registered polled functions. This function will not exit until the application is terminated. Choice of threading models is: TW_THREADING_SINGLE - Use the thread this function is called on to service registered polled functions TW_THREADING_TASKER - Use the built in tasker functionally of the C SDK to call all polled functions.

Parameters
intervalMsecPolling period in milliseconds.
threadingModelThreading model to use.
messageHandlerThreadCountNumber of message handling threads to spawn.
void twExt_PerformPolledFunctions ( DATETIME  now,
void *  params 
)

A tasker style handler function which can be called directly or by the tasker to execute all registered polled functions for any Template or Shape.

Parameters
nowUnused.
paramsUnused.
void twExt_RegisterPolledShapeFunction ( twOnPolled  polledFunction,
char *  shapeName 
)

Register a callback function that takes a single char* that will be called once for each Thing that uses the thing shape "shapeName". Use this function to add polled or processScanRequest style functions that should be called on any thing based on this thing shape.

Parameters
polledFunctionA function using the style defined by twOnPolled. Ex. myPolledFunction(char* entityName);
shapeNameThe name of the shape this function should be attached to.
void twExt_RegisterPolledTemplateFunction ( twOnPolled  polledFunction,
char *  templateName 
)

Register a callback function that takes a single char* that will be called once for each Thing that uses the template "templateName". Use this function to add polled or processScanRequest style functions that should be called on any thing based on this template.

Parameters
polledFunctionA function using the style defined by twOnPolled. Ex. myPolledFunction(char* entityName);
templateNameThe name of the template this function should be attached to.
void twExt_RemovePolledFunction ( twOnPolled  polledFunction)

Remove the polled function from the list of active polled functions.

Parameters
polledFunctionA pointer to the polled function to be removed.
void twExt_Start ( uint32_t  dataCollectionRate,
enum twThreadingModel  threadingModel,
uint32_t  messageHandlerThreadCount 
)

Starts a thread to monitor all things with registered polled functions. Use this function if you want control of the calling thread to perform other work inside your application. This function relies on the tasker to call polled functions on a thread it creates.

Parameters
intervalMsecPolling period in milliseconds.
threadingModelThreading model to use.
messageHandlerThreadCountNumber of message handling threads to spawn.
int twExt_Stop ( )

Shut down all threads associated with your current threading model. You should call twExt_Stop() before twApi_Disconnect() when shutting down your active threading model.

Returns
TW_OK is succeeds, otherwise TW_THREADING_MODEL_FAILED_SHUTDOWN
int twExt_WaitUntilFirstSynchronization ( uint32_t  timeoutMills)

Block until it can confirm that you have received at least one synchronization message from the server. It can be used to wait until your application is cleared to start posting property changes.

Parameters
timeoutMillsMaximum wait time in milliseconds.
Returns
TW_OK is succeeds, otherwise TW_SUBSCRIBED_PROPERTY_SYNCHRONIZATION_TIMEOUT