I am expecting the ':locked' attribute to ensure that no other thread, intentional or otherwise, will access the subroutine while the active thread has control.

If you read the threads documentation, the :locked attribute isn't mentioned because it does nothing. Quite literally nothing. It is a noop.

It is non-functioning leftover from perl5005 threads that has never had any affect on iThreads.

I am presuming that you are referring to the independent threads that manage the print_manager and the thread_timer aspect of the program.

No. Having a couple of other threads outside of the worker pool isn't a problem. That's quite normal.

The problem is that you manage each of the threads in your 'pool' as individual entities. Ie. Each has a separate queue. Which means that your dispatcher has to allocate and coordinate work to each worker individually. The result of which is the excessive complexity of your implementation. With a traditional thread pool, all the threads are identical and often anonymous. And they get their work from a single work queue.

Think of this as analogous to the baggage carousels in airports. The bags are loaded onto the belt back-of-house, and the 'workers', passengers in this scenario, collect the bags from the carousel entirely independently of each other, and of the loading.

What you've done is to replace the carousel with a fan of one-to-one conveyors, and placed a dispatcher between the inbound conveyor and that fan. He has to take the bags off the inbound conveyor, read the labels, and decide which of the fan of conveyors he needs to place each bag on for it to get to the appropriate customer.

You've added huge complexity--the fan of one-customer-at-a-time, one-bag-at-a-time conveyors; and created a bottle-neck--the dispatcher--upon whom all the customers have to wait. Not to mention all the tagging, control and coordination problems created by the need to route each customer to the right conveyor and each bag to the right customer.

In the process, you've made some very strange choices.

For example, your 'jobs' queue. You create a shared array, onto which you push all your jobs en-mass. You then pull them off that queue and feed them onto the worker's individual queues. But it is the same thread that puts them on the jobs queue as takes them off. So there was no need for a shared data-structure--with all the size and performance penalties it entails. A simple array would have sufficed.

And the rest of your code is full of similar anomalies.

I'm trying very hard not to be negative of someone trying to do what I have declined to do, but the truth is that as a tutorial, your code is actually worse than no tutorial, because it teaches a lot of bad practices. And once out there, they become very hard to unlearn, and the time-bombs they will create become very hard to diffuse.

Given the (unwritten, despite your original claim to "solid documentation") 'spec' of your 400+ line program, its function (such as it is) can be easily and far, far more clearly achieved with 30 or 40 lines, of cleaner, clearer and more easily maintained code. It is typical of code written to "demonstrate some functionality" rather than solve a problem. It is also typical of a program written by someone who has yet to try and use iThreads in a real application.

Sorry.