TLSAllocA

Allocate Thread-Local Storage index (V51.46)

Declaration

Source position: exec.pas line 2345

Arguments

Function result

a global index to Thread-Local Storage or TLS_INVALID_INDEX if no index was available due to lack of resources.

Description

Allocates a Thread-Local Storage index from the global index pool.

Available Tags

TLSTAG_DESTRUCTOR

A function to call when TLSCallDestructors() function is called or when the task/process terminates. Default is to call no function. Passing nil has the same effect. destructor is called as

procedure(value: APTR; userdata: APTR);

TLSTAG_USERDATA

Optional userdata to the TLSTAG_DESTRUCTOR function. The default value is nil if thistag is not specified.

The destructor function should not take very long to complete. It is for example unwise to ask for user input or similar. The destructor may call TLSSetValue(index, nil) for the same index. It is also legal to TLSSetValue some other index to non-nil value. Refer to TLSCallDestructors documentation for details about this.

Care must be taken that all accessed resources are valid and accessible during destructor execution. It is also up to the caller to implement any arbitration of resources with for example signalsemaphore, if needed.

It is the responsiblity of the TLSAlloc caller to ensure that code pointed by TLSTAG_DESTRUCTOR will remain executable for the duration teh index is in use. Specifically the application may not terminate (which unloads the code segment) if there are any other tasks running which may call the destructor.

If you do not call TLSCallDestructors yourself the destructor will be executed when the process/task is about to terminate. For process this happens before struct Process fields are deallocated.

Attention

The destructor function must remain callable for as long as index remains allocated.

It is illegal to TLSFree an index while it is still being used by TLSGetValue and/or TLSSetValue by other tasks. The caller is responsible for making sure this does not happen.

See also

Example

uses
  Exec;
function func(value: APTR; userdata: APTR): APTR;
begin 
  FreeVec(value);
end;
// ...
var
  TLSIndex: LongWord;
begin
  TLSIndex := TLSAlloc([TLSTAG_DESTRUCTOR, AsTag(@func),
                        TLSTAG_USERDATA,   AsTag(something),
                        TAG_DONE]);
  if TLSIndex <> TLS_INVALID_INDEX then
  begin

    // ... more code ...

    TLSFree(TLSIndex);
  end
end.