Wiki improvements

[fxm]

See current version of the 'Event Handling' new page in the Programmer's Guide:
Programmer's Guide / Other Topics / Event Handling

[speedfixer]

Excellent.
Enough of the nasty details are revealed to let a beginner know that his key input isn't as simple as it may seem to be.

david

[fxm]

There are always 2 pages of the Programmer's Guide to complete or fill in:
- Executables (page to complete)
- External Graphics File Formats (page to fill in)
Are there volunteers?
These 2 subjects are outside my skill, but from a draft page in the forum, I can on the other hand take care of the formatting and the insertion in the corresponding documentation page.

[VANYA]

External Graphics File Formats

fxm! Is BLOAD, BSAVE able to download anything else in addition to BMP? What else can be supplemented by other than what is described in Help? I always thought these teams the capability to download images BMP. Am I wrong?

[fxm]

These 2 subjects are outside my skill

coderJeff's advice to fill in this page:

For external graphics file formats topic: what is supported by BLOAD & BSAVE. To be cross platform, the QB/BMP formats that can be loaded/saved are hard coded in the rtlib. So, this is will be a description of what is specifically supported by the rtlib.

[fxm]

'changelog.txt':

- add THREADSELF in ./inc/fbthread.bi to return the thread id of the current thread (adeyblue)

@Jeff,
@adeyblue,

About the new 'ThreadSelf' keyword:
- I am surprised that under Windows the 'thread id' returned by 'ThreadSelf()' has the same value as the 'thread handle' returned by 'ThreadCreate()' (as under Linux).
- If this is always true, then why use 2 different naming (the true naming should be 'thread handle' for both)?

(see https://docs.microsoft.com/en-us/window ... dentifiers)

Code: Select all

#include "fbthread.bi"

Dim As Any Ptr phandle(1 To 10)
Dim Shared As Any Ptr pmutex0
Dim Shared As Any Ptr pmutex

Sub myThread (Byval p As Any Ptr)
    Mutexlock(pmutex0)
    Dim As Any Ptr phandle = *Cptr(Any Ptr Ptr, p)
    Mutexunlock(pmutex0)
    Dim As Any Ptr pid = Threadself()
    Mutexlock(pmutex)
    Print "Thread handle: " & phandle, "Thread id: " & pid
    Mutexunlock(pmutex)
    Sleep 100, 1
End Sub

pmutex0 = Mutexcreate()
pmutex = Mutexcreate()
For I As Integer = 1 To 10
    Mutexlock(pmutex0)
    phandle(I) = Threadcreate(@myThread, @phandle(I))
    Mutexunlock(pmutex0)
Next I

For I As Integer = 1 To 10
    Threadwait(phandle(I))
Next I
Mutexdestroy(pmutex0)
Mutexdestroy(pmutex)

Sleep

• output example under Windows:

  Code: Select all

  Thread handle: 12528352     Thread id: 12528352
  Thread handle: 12528936     Thread id: 12528936
  Thread handle: 12530648     Thread id: 12530648
  Thread handle: 12529520     Thread id: 12529520
  Thread handle: 12528504     Thread id: 12528504
  Thread handle: 12528560     Thread id: 12528560
  Thread handle: 12528744     Thread id: 12528744
  Thread handle: 12530808     Thread id: 12530808
  Thread handle: 12531160     Thread id: 12531160
  Thread handle: 12530968     Thread id: 12530968

[fxm]

Looking at 'tests/threads/self.bas', I see that the test is effectively checking for equality between the 'CreateThread()' return and the 'ThreadSelf()' return (for the same thread).
The chosen context is therefore that of Linux only and not of Windows.

My suggestion above (same naming in documentation for both returns = 'thread handle' and not 'thread id') seems best to avoid confusion with the known behavior under Windows (where 'thread handle' and 'thread id' have different values).

[adeyblue]

I don't update the changelog, because that seems rather presumptious on my part on both if and when the change will be accepted. I'm sure at some point Jeff's gonna look at a pull request and say, nah man, get outta here.

But yes, the idea is that ThreadSelf of a running thread returns the same value that ThreadCreate did when it created it, and that these ids, handles, whatever you want to call them, uniquely identify a FB thread (and only a FB thread, nothing platform specific) until it exits or until it is ThreadWait/ThreadDetach-ed, whichever is longer. The first/primary/main thread also has its own unique id, but obviously, that doesn't have a ThreadCreate to compare to.

It just seemed slightly weird in the engineering it required for a thread to know its own id (or whatever), that you had to involve mutexes when creating the thread and explicitly pass it along. ThreadSelf means you don't have to bother with any of that now because each thread now knows who it is. Similar to most other manual threading systems.

ThreadCreate calls it a handle, that's fine. As the handle is now a unique value for the lifetime of the thread (this previously wasn't guaranteed), it's now a defacto id too.

[fxm]

the idea is that ThreadSelf of a running thread returns the same value that ThreadCreate did when it created it, and that these ids, handles, whatever you want to call them

For the naming, I think the easiest is to keep 'thread handle' for 'ThreadCreate/ThreadDetach/ThreadWait' and 'thread id' for 'ThreadSelf' as I entered in the documentation, but explain in the 'ThreadCreate' and 'ThreadSelf' pages the equivalence of the two names with regard to their values.
For naming, the only term 'thread handle' should be used throughout the documentation.
(done)

It just seemed slightly weird in the engineering it required for a thread to know its own id (or whatever), that you had to involve mutexes when creating the thread and explicitly pass it along. ThreadSelf means you don't have to bother with any of that now because each thread now knows who it is.

I guess you are also referring to my example above to pass the handle returned from ThreadCreate(), but another usage may be to emulate a sort of TLS (Thread Local Storage) from this unique id.

[coderJeff]

About the new 'ThreadSelf' keyword:
- I am surprised that under Windows the 'thread id' returned by 'ThreadSelf()' has the same value as the 'thread handle' returned by 'ThreadCreate()' (as under Linux).
- If this is always true, then why use 2 different naming (the true naming should be 'thread handle' for both)?

Sorry, fxm. I didn't think much about it at the time. In this case 'thread id' should be 'thread handle' as in ThreadCreate(). I wrote 'thread id' in the changelog and 'thread handle' in the commit.

Under the hood:
The Any Ptr returned by ThreadCreate() is the same Any Ptr returned by ThreadSelf().
The Any Ptr is a pointer to memory allocated by fb runtime that contains a structure:
The rtlib internal structure (FBTHREAD) contains:
- the system's thread handle or thread id as determined by the operating system. From the user's perspective, they don't know (or should care) as we don't expose any API for it.
- plus some extra flags that rtlib uses to track thread status
- the Any Ptr (to FBTHREAD) is valid until the thread exists and uniquely identifies the thread from fb's / user's perspective

[fxm]

New page ThreadSelf created in documentation:
- KeyPgThreadSelf → fxm [new page created]
- ProPgMtThreads → fxm [added link to ThreadSelf]
- KeyPgThreadCreate → fxm [added link to ThreadSelf]
- CatPgThreading → fxm [added link to ThreadSelf]
- CatPgFunctIndex → fxm [added link to ThreadSelf]
- CatPgFullIndex → fxm [added link to ThreadSelf]
- ProPgPrebuiltLibraries → fxm [added link to ThreadSelf]
- PrintToc → fxm [added link to ThreadSelf]

[SARG]

The meaning of ThreadSelf is not obvious, at least for me.
ThreadGetHandle() (a bit long) or ThreadHandle() seem clearer.

And keep "handle" everywhere as it's its purpose.

[fxm]

The meaning of ThreadSelf is not obvious, at least for me.
ThreadGetHandle() (a bit long) or ThreadHandle() seem clearer.

I think that 'ThreadSelf' comes from the 'Thread_Self' under Linux.

And keep "handle" everywhere as it's its purpose.

Done.

[SARG]

GetCurrentThread Windows's API :-)

"handle" thanks

[fxm]

Under Windows:

A thread can use the GetCurrentThread function to retrieve a pseudo handle to its own thread object. This pseudo handle is valid only for the calling process; it cannot be inherited or duplicated for use by other processes. To get the real handle to the thread, given a pseudo handle, use the DuplicateHandle function.