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

See Also

TUFXOP_Clear, TUFXOP_GetStorage

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

See Also

TUFXOP_Init, TUFXOP_GetStorage

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.

See Also

TUFXOP_Init, TUFXOP_Clear

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

See Also

TUFXOP_ReleaseLock

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.

See Also

TUFXOP_AcquireLock

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

See Also

TUFXOP_Init, TUFXOP_Clear

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