Documentation and Resource Tracking Issue

[tpunt]

This issue tracks the documentation/resources issues.

The following places need updating:

• [x] examples/
• [ ] pthreads.org website
  • [x] Remove outdated content
  • [ ] Include new information on the Volatile class
  • [ ] Include new information on the Socket class
• [x] php.net docs:
  • [x] Workers no longer have to track their work
  • [x] Collectable no longer extends Threaded. Threaded should be shown to implement Collectable
  • [x] Collectable::setGarbage no longer exists
  • [x] Mention Threaded::getTerminationInfo alternative (try...catch, given PHP 7 uses mostly exceptions)
  • [x] Mention Threaded::from alternative (anonymous classes)
  • [x] Mention Threaded::lock and Threaded::unlock alternatives (Threaded::synchronized)
  • [x] Document Threaded::notifyOne
  • [x] Volatile class needs documenting
  • [ ] Socket class needs documenting
• [ ] Everywhere: pthreads is now only compatible with PHP 7.2+

[dktapps]

The Socket class is as-yet undocumented.

[tpunt]

Thanks for the reminder, @dktapps. I've added it to the list.

[dktapps]

This is just my humble opinion but...

The php.net documentation is very confusing and doesn't include important information in a lot of places. For example: the Threaded class documentation does not mention anywhere that non-Threaded objects are serialized when set as members of Threaded objects. It's mentioned in the introduction, but the intro is one giant blob of TL;DR. In fact there's only one place where the word "serialized" is used in the intro even, which implies that this is true, but is not explicitly documented.

It's also very confusing how the v2 and v3 documentation is mixed together - I often see people introduced to pthreads and come out totally confused by the documentation. Some things are listed there which don't exist in pthreads v3 (yes, this is noted but often users only think "I'm using pthreads", not "I'm using pthreads v3"). If there's any way that the two could be separated (so that v2 has entirely separate documentation to v3, with v3 being default), it would go a long way towards making the docs more understandable.

I don't mean to sound like I'm dissing anyone's work, but the php.net documentation could be a lot better than it is imho.

[tpunt]

The php.net documentation is very confusing and doesn't include important information in a lot of places.

Agreed. It does need more work, but I'm having difficulty finding the time at the moment. The serialisation aspect definitely does need mentioning, though.

It's also very confusing how the v2 and v3 documentation is mixed together

When I originally updated the docs, v2 was still common-place. So the docs for both versions of pthreads, along with how to migrate to v3, needed to be mentioned. Given that v3 has been out for over 2 years now, maybe the docs on v2 could be retired completely, such that the manual only refers to v3. This should make things clearer.

The only downside to this is that there exists a lot of information on v2 still. If developers read such articles and search for the docs on any of the removed classes or methods, then they may be left wondering why there is no documentation about them.

If there's any way that the two could be separated

Unfortunately, that's not possible with the docs on php.net. Only one version exists, where mentions of changes in previous versions needs to be made all in one place. It's less than ideal, to say the least. I prefer the way documentation sites work in other communities, where the documentation is versioned alongside the library, enabling for multiple versions of the documentation to exist (thereby preventing clutter in the docs from old library versions).

I don't mean to sound like I'm dissing anyone's work, but the php.net documentation could be a lot better than it is imho.

I'm always happy to hear criticisms :) And I do agree with your points here, but for now, it comes down to a lack time.

[ghost]

Is there any updates on this? Specifically about the socket class - I have no idea what it is for as there is no documentation about, not even were I able to find in the source a summary.

[joeyhub]

I'm not sure why the socket class is there either. I suspect it's something that could be removed.

The examples in the examples folder are a bit more useful than what's in the PHP manual. Not sure what's in the tests. There might come a point where I'll just concat all the source files and casually read them.

There's kind of an issue as I'm not really sure how seriously this extension takes itself :D which might undermine it.

Although it's often branded as "unsafe" for me it's potentially the stop gap for accomplishing certain things in PHP that will ultimately need changes in the core and particularly core extensions. As far as I'm concerned the unsafe part first and foremost is if you use it wrong.

Getting things right is important and this is a library with a lot under the hood that people need to know about. It's often vague on basic use let alone what's happening beneath the surface.

I think things like socket really do seem spurious. Personally I'd just delete it and focus on the threading. Same for things like the extend function (messing around with multiple inheritance). It would probably be better to let people do that stuff in user space rather than making things more confusing with what seems like conveniences but can really make a mess. Threading is already a major hack.