- Introduction
- Introduction to Multithreading
- Introduction to OmniThreadLibrary
- Tasks vs. Threads
- Locking (vs.) Messaging
- TOmniValue
- High-level multithreading
- Blocking Collection
- Async
- Future
- Join
- ParallelTask
- BackgroundWorker
- Pipeline
- ForEach
- ForkJoin
- Low-level multithreading
- Introduction
- Four ways to create a task
- Task Controller Needs an Owner
- Thread Pooling
- GOmniThreadPool
- Lock-free Collections
- Bounded Stack
- Bounded Queue
- Dynamic Queue
- Event Monitor
- Simple Tasks
- Name
- UniqueID
- Parameters
- Communication
- Comm
- Termination
- Terminate
- Terminated
- Stopped
- TerminateEvent
- WaitFor
- ExitCode
- SetExitStatus
- Exceptions
- FatalException
- DetachException
- SetException
- ChainTo
- Groups – Join/Leave
- MonitorWith
- Enforced
- Unobserved
- CancellationToken/CancelWith
- Lock/WithLock
- Counter/WithCounter
- ThreadData
- SetPriority
- WaitForInit
- SetQueueSize
- TOmniWorker Tasks
- Initialize, Run, Cleanup
- Timers
- Communication
- Sending to the Owner
- Receiving from the Owner
- Talking to other tasks
- Invoke
- Windows Message Processing
- Alertable
- MsgWait
- UserData
- RegisterWaitObject
- Task Group
- Synchronization
- IOmniCriticalSection
- Hassle-Free Critical Sections (TOmniCS)
- TOmniMREW
- Pessimistic, Optimistic and Busy-Wait Initialization
- Inverse Semaphore
- Cancellation Token
- GOmniCancellationToken
- Miscellaneous Stuff
- TOmniValue
- TOmniValueObj
- TOmniWaitableValue
- TOmniValueContainer
- TOmniCounter
- IOmniInterfaceDictionary
- TOmniRecordWrapper
- IOmniAutoDestroyObject
- Environment
- Hooks
- IOmniTaskControlList
- Atomic instructions (CAS, Move)
- Communication Observers
- How-to
- Web Download and Database Storage
- Background Worker and List Partitioning
- Background File Scanning
- Building a Connection Pool
- QuickSort
- Parallel Search in a Tree
- Multiple Workers with Multiple Frames
Pages
▼
Tuesday, January 31, 2012
OmniThreadLibrary Documentation–an Outline
That’s how it’s going to look. If you feel I have left something out, now is the time to raise your voice.
A Glossary would be a great addition as well (IMO). e.g. Connection pool (is that database connections, thread connections, etc). For multi-threading newbs, they can then at least understand the "language".
ReplyDeleteThat is a good idea but I don't know if my command of the English language is good enough to write something like that.
ReplyDeleteWell, on your podcast with Jim McKeeth you had a noticeable accent that made understanding you difficult at times, but I've never had any trouble with your written English. You're pretty good at it, and I'm sure if the users come across something confusing, we can point it out and offer suggestions on how to improve the wording.
DeleteI am willing to help with the glossary. I'm a native english speaker and Delphi guy.
DeleteWarren
warren dot postma at the usual google mail stuff
Warren, great & thanks!
DeleteDon't worry, it's not as important to do some mistakes in your translations as it is in your code :-D
ReplyDeleteThank you again for this great piece of work !
With regards to the Glossary, it may even be worthwhile getting assistance by crowd-sourcing the Glossary. I'm sure that there is enough knowledgeable people in the community who could send in contributions to you and then you can add them or modify them to fit into the glossary. Just add the terms to the Glossary for those words that may be difficult to explain and let the Community contribute.
ReplyDeleteOnce again, gabr thanks for making your library so accessible to us all.
+1 for crowdsourcing. You could even make the documentation a wiki, a bit like Embarcadero's.
ReplyDeleteAlso, thanks for considering documentation at all, and planning it out to this level. It's great to see a project like this with great documentation.
Yes, definitely consider wiki-ising it. People can add their own tips and tricks and even better code samples!
DeleteI must say, I'm very eager to start reading it just from the outline... Documentation like this is the difference between an interesting project, and being adopted as mainstream, IMHO. It's rare to have such a well thought out point to point user guide with technical documentation.
Fantastic work.
I'm sure you can find volunteers to clean up some of the English. I'd gladly offer my services on that front.
ReplyDeleteThis looks great, I've been meaning to check out OmniThreadLibrary for some time, but just haven't had time to sit down and experiment with it. Structured documentation like this will definitely get me trying it out and hopefully using it effectively sooner, which makes it much more appealing :)
ReplyDeleteMost of your users won't need this, but under item 2 (Introduction to Multithreading), it would be great to add two subitems:
ReplyDeletea. Why multithread?
b. When not to multithread
Under item 3, add "Why use OmniThread?"
Thanks everybody for comments and contributions. I agree with all of them, especially crowdsourcing some parts.
ReplyDeleteIndeed, documentation will definitely be available in a wiki format. I also intend to publish a free pdf and maybe a payable e-book variant.
One topic I haven't seen covered anywhere so far is using the OTL while dealing with COM/OLE objects. Or is that something you generally wouldn't recommend doing?
ReplyDelete@Oliver, this is something I know nothing about. I would presume that it behaves exactly the same as the TThread does.
ReplyDeleteI assume you will also insert your usual "and for those using databases, good luck" comment :)
ReplyDeleteI'm happy to contribute if you wiki-ise it, or proofreading etc if you want to email me a copy of anything. If you do do an ebook, please don't do it by converting the PDF, just point Calibre at the wiki.
I'm using databases (dbExpress & MSSQL) with threading (not OmniThread). So far the only gotcha is that you must ensure there's a different connection object per thread.
DeleteAll I did is have a connection pool and GetConnection / FinishedWithConnection functions that ensure there's always a connection per thread ID. The connections are just reference counted to ensure they're not freed whilst in use.
To be fair though, databases are only accessed to build a cache, so perhaps I'm not seeing some of the complexities?
I have included your notes in the Wiki (http://otl.17slon.com/book/doku.php?id=book:howto:databases). If you don't agree with that (please check the conditions at http://otl.17slon.com/book/doku.php), send me an email or reply here and I'll remove your contribution.
Delete[I am pretty sure that you'll be OK with it but I want to play this fair and safe.]
Pfffff, databaseses :( While I know they are important, I'm just not competent in this area. I am still looking for a brave soul that knows about databases, needs multithreading and would pursue the quest to multithreaded database application. I would provide all support on the 'multithreading' part and add any missing parts to the OTL - and at the end blog about it, of course.
ReplyDeleteThanks for the offer, much appreciated. I'll keep you in mind.
Don't worry, I would never do that. I will most probably write everything in the Word and synchronize it with a Wiki when I make any significant contribution. I know this sounds like a weird plan but I need a WYSIWYG environment to write efficiently - that's something I've found out a long time ago. I simply must see beautiful font on the screen or I'm all "bleuch why I'm spending my time on this crap".
I think part of the reason for the paucity of documentation is that it's either very, very simple (one session or connection per thread. The end). Or it's very, very complex (ADO async, hand-rolled connection sharing, etc). If you get into NoSQL it becomes simple again, and in many ways I'd rather write sample code that does that.
DeleteI'm happy to write up some commentary on databases once there's a spot for it and I can see the style of what you're writing. I've used OTL somewhat and databases rather a lot (and the combination whenever I've used OTL seriously).
The simple approach is one connection per thread as noted above, and that's easy to do. But that can be wasteful of connections (which can lead to server thrashing), and if you're doing ye olde two tier development makes threading pretty much useless, since your database access is tied to the GUI which is tied to the main VCL thread.
In that situation you can, however, cheat this quite significantly by opening datasets in threads but re-setting datasource.Active in the main thread when the dataset has finished opening (and changing the underlying session appropriately, of course). Mostly - this sort of trickery is undocumented and unsupported, but can give you huge performance wins with relatively small code changes (because you're opening slow queries in parallel). You can sometimes do this via ADO async mode but that has its own challenges.
Moz, thanks for the offer.
DeleteIf you scroll to the end of the chapter list at http://otl.17slon.com/book/doku.php, you'll see "OmniThreadLibrary and Databases". If you create a wiki account, I'll give you write access.
I have included your notes in the Wiki (http://otl.17slon.com/book/doku.php?id=book:howto:databases). If you don't agree with that (please check the conditions at http://otl.17slon.com/book/doku.php), send me an email or reply here and I'll remove your contribution.
Delete[I am pretty sure that you'll be OK with it but I want to play this fair and safe.]
Wiki: http://code.google.com/p/omnithreadlibrary/wiki/OtlBookContents
ReplyDeleteI'll probably move the "OTL Book Wiki" somewhere else as the Google Code Wiki is quite clumsy.
"Final"(*) Wiki URL: http://otl.17slon.com/book/doku.php
ReplyDelete(*) May still change if there's a good reason.
It's what some of my friends were looking for to get some more deep use of OTL.
ReplyDeleteThanks!