Operations¶

TUFXOP_Init¶

Initializes the named shared storage¶

TUFXOP_Init [/Q[=q] /Z[=z] [/N=name]]

The TUFXOP_Init operation initializes the shared storage.

Parameters¶

This operation has no parameters.

Flags¶

/N=name

Initializes the shared storage named by name. The name is case insensitive.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

If the /N flag is omitted, then the default global is used as name.

If a shared storage with the given name already exists it is released from memory before a new storage with the same name is created.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Initializes a named shared thread storage and puts some data into it¶

Function TUFXOP_Init_example1()

    TUFXOP_Init/N="myStorage" // Init shared thread storage "myStorage"
    TUFXOP_GetStorage/N="myStorage"/TS wv // Get thread-local storage wave in name space "myStorage", here for main thread
    Make/FREE data
    wv[0] = data // put some data in the storage
    TUFXOP_Clear/N="myStorage" // Clear shared thread storage "myStorage"
End

TUFXOP_Clear¶

Releases the named or all shared storages from memory¶

TUFXOP_Clear [/Q[=q] /Z[=z] [/A] [/N=name]]

The TUFXOP_Clear operation releases shared storages from memory and clears all locks.

Parameters¶

This operation has no parameters.

Flags¶

/A

Releases all shared storages from memory.

/N=name

Releases the shared storage name from memory. The name is case insensitive.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

Only one of /A or /N is allowed.

If the /N flag is omitted, then the default global is used as name.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Inits a shared thread storage, puts some data in and clears it again¶

Function TUFXOP_Clear_example1()

    TUFXOP_Init // Initialises shared thread storage named "global"
    TUFXOP_GetStorage/TS wv // Get the thread-local storage wave for the main thread
    Make/FREE data
    wv[0] = data // put some data in the storage
    TUFXOP_Clear // Clear shared thread storage "global"
End

TUFXOP_GetStorage¶

Retrieves a shared or thread-local storage¶

TUFXOP_GetStorage [/Q[=q] /Z[=z] [/TS] [/N=name]] storage

The TUFXOP_GetStorage operation returns the named shared or thread-local storage wave.

Parameters¶

storage: Wave reference that is returned from the XOP. The wave reference refers, depending on the /TS flag, to the shared or thread-local storage wave.

Flags¶

/N=name

Refers to the name of the storage. The name is case insensitive.

/TS

If set then the thread-local storage wave is returned.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

The operation returns in storage a reference to a wave reference wave. This wave will have initially one point. The user can resize that wave at will.

When this wave is returned with /TS it is actually stored in another wave reference wave which will be returned without /TS. In that way the user can choose to access thread-local storage or all storage.

With /TS the number of actually used elements depends on the number of threads that called this operation with the /TS flag. The number of elements used can be retrieved by NumberByKey("Index", note(storage)). The elements from index on are null wave references.

When operating on the data without /TS from other threads the programmer has to take care not to concurrently access the same data, e.g. by using a lock. Use TUFXOP_Clear or TUFXOP_Init with the same name to release the current wave from memory.

Each storage space accessed via /N is completely independent of each one another.

If the /N flag is omitted, then the default global is used as name.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Counts up multi threaded in parallel in thread-local storage.¶

threadsafe static Function gs_helper1()

    TUFXOP_GetStorage/TS threadLocalStorage
    // threadLocalStorage is a wave reference wave which has one element
    // It is unique for the preemptive thread executing this function
    // We therefore don't need any locking as other threads which
    // run concurrently right now will get their own distinct wave

    if(!WaveExists(threadLocalStorage[0]))
        // we are called the first time
        Make/FREE/D/N=1 data // Create a data wave
        threadLocalStorage[0] = data // put it in the thread-local storage
    else
        WAVE data = threadLocalStorage[0]
    endif

    data[0] += 1 // Count up in this thread
End

Function TUFXOP_GetStorage_example1()

    variable numThreads, i, count

    TUFXOP_Init

    Make/FREE/N=1000 wIndex

    // Call function with 32 parallel threads
    // using /NT ensures that we get 32 threads on all machines
    MultiThread/NT=32 wIndex[] = gs_helper1()

    // Get shared thread storage wave
    // This is a wave-ref wave which will have as many elements as threads were running
    TUFXOP_GetStorage allStorage
    numThreads = NumberByKey("Index", note(allStorage))
    printf "%d threads were running.\r", numThreads

    for(i = 0; i < numThreads; i += 1)
        // fetch thread local storage from i'th thread
        WAVE/WAVE threadLocalStorage = allStorage[i]
        WAVE data = threadLocalStorage[0]
        count += data[0] // Sum up all thread-local counts
    endfor

    // Print out that 1000 counts were gathered
    printf "Gathered %d counts.\r", count

    TUFXOP_Clear
End

Output:¶

32 threads were running.
Gathered 1000 counts.

Counts up multi threaded in parallel in the shared thread storage with locking.¶

threadsafe static Function gs_helper2()

    TUFXOP_AcquireLock

    TUFXOP_GetStorage globalStorage
    WAVE data = globalStorage[0]

    data[0] += 1

    TUFXOP_ReleaseLock
End

Function TUFXOP_GetStorage_example2()

    TUFXOP_Init

    TUFXOP_GetStorage globalStorage

    Make/FREE/N=1 data
    globalStorage[0] = data

    Make/FREE/N=1000 wIndex

    // Call function with 32 parallel threads
    MultiThread/NT=32 wIndex[] = gs_helper2()

    // Print out that 1000 counts were gathered
    // wave reference to data is still up-to-date
    printf "Gathered %d counts.\r", data[0]
End

Output:¶

Gathered 1000 counts.

TUFXOP_AcquireLock¶

Acquires lock.¶

TUFXOP_AcquireLock [/Q[=q] /Z[=z]] [/N=name]]

The TUFXOP_AcquireLock operation acquires a lock.

Parameters¶

This operation has no parameters.

Flags¶

/N=name

Acquires the lock identified by name. The name is case insensitive.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

If the /N flag is omitted, then the default global is used as name.

If the lock is already locked the operation waits indefinitly until it gets unlocked in another thread. The waiting can be aborted by the user.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Acquires the global lock and releases it again.¶

Function TUFXOP_AcquireLock_example1()

    // acquire and release the lock named "global"
    TUFXOP_AcquireLock
    TUFXOP_ReleaseLock
End

Acquires two named locks and releases them again.¶

Function TUFXOP_AcquireLock_example2()

    TUFXOP_AcquireLock/N="first" // Acquire named lock "first"
    TUFXOP_AcquireLock/N="second" // and another
    TUFXOP_ReleaseLock/N="first" // release the first one
    TUFXOP_ReleaseLock/N="second" // and the second
End

TUFXOP_ReleaseLock¶

Releases a lock¶

TUFXOP_ReleaseLock [/Q[=q] /Z[=z]] [/N=name]]

The TUFXOP_ReleaseLock operation releases the lock.

Parameters¶

This operation has no parameters.

Flags¶

/N=name

Releases the lock identified by name. The name is case insensitive.

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

If the /N flag is omitted, then the default global is used as name.

The implementation allows to lock from thread A and unlock from thread B.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Add up counts in the same data wave multithreaded using a lock¶

threadsafe static Function rl_helper(WAVE data)

    TUFXOP_AcquireLock // Acquire "global" lock
    data[0] += 1
    TUFXOP_ReleaseLock // Release "global" lock
End

Function TUFXOP_ReleaseLock_example1()

    Make/FREE/N=1 data

    Make/FREE/N=1000 wIndex
    // Call function with 32 parallel threads
    MultiThread/NT=32 wIndex = rl_helper(data)
    // Print out that 1000 counts were gathered
    printf "Gathered %d counts.\r", data[0]
End

Output:¶

Gathered 1000 counts.

TUFXOP_RunningInMainThread¶

Returns information if the current thread is the main thread.¶

TUFXOP_RunningInMainThread [/Q[=q] /Z[=z]

The TUFXOP_RunningInMainThread operation returns in V_value the information if the current thread is the main thread of Igor Pro or not.

Parameters¶

This operation has no parameters.

Flags¶

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

If the current Igor Pro thread is the main thread 1 is returned in V_value. Otherwise 0 is returned.

Output Variables¶

V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.
V_value: Set to one if the current thread is Igor Pros main thread, zero otherwise.

Examples¶

Prints out if a function was running in main thread or not.¶

threadsafe static Function rmt_helper()

    TUFXOP_RunningInMainThread
    printf "This threaded execution is running %sin the main thread.\r", SelectString(V_Value, "not ", "")
End

Function TUFXOP_RunningInMainThread_example1()

    Make/FREE/N=10 wIndex
    // Call function with 32 parallel threads
    MultiThread/NT=32 wIndex = rmt_helper()
    rmt_helper()
End

TUFXOP_Version¶

Returns version information about the TUF XOP:¶

TUFXOP_Version [/Q[=q] [/Z[=z]]

The TUFXOP_Version operation returns version information about the XOP.

Parameters¶

This operation has no parameters.

Flags¶

/Q=q

Controls error reporting and verbose output to the history area.

/Q=1:: No error reporting to the history area.
/Q:: Is identical to /Q=1.
/Q=0:: Is the same as omitting the flag.

/Z=z

Controls runtime error reporting. The error code is always returned in V_flag.

/Z=1:: Suppresses generation of runtime errors.
/Z:: Is identical to /Z=1.
/Z=0:: Is the same as omitting the flag.

Details¶

The operation prints version information to the history area when called from the command line.

Output Variables¶

S_value: Returns version information of the XOP.
V_flag: Set to a non-zero value if an error occurred and to zero if no error occurred.

Examples¶

Shows TUF XOP version information¶

Function TUFXOP_Version_example1()

    TUFXOP_Version
    print S_Value
End

Error Codes¶

The XOP operations can return the following error codes:

XOP error codes¶

// Error constants for TUFXOP XOP
Constant TUFXOP_OLD_IGOR = 10001
Constant TUFXOP_UNHANDLED_CPP_EXCEPTION = 10002
Constant TUFXOP_ERR_ASSERT = 10003
Constant TUFXOP_ERR_CONVERT = 10004
Constant TUFXOP_ERR_INVALID_TYPE = 10005

// Name is invalid
Constant TUFXOP_ERR_INVALID_NAME = 10006

// Used flags exclude each other
Constant TUFXOP_ERR_EXCLUDING_FLAGS = 10007

Operations¶

TUFXOP_Init¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

TUFXOP_Clear¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

TUFXOP_GetStorage¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

TUFXOP_AcquireLock¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

TUFXOP_ReleaseLock¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

TUFXOP_RunningInMainThread¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

TUFXOP_Version¶

Parameters¶

Flags¶

Details¶

Output Variables¶

Examples¶

See Also¶

Error Codes¶