Understanding hb_mutexSubscribeNow()

[Eric Lendvai]

I am trying to prepare some more updated documentation about Harbour Multi-threading.
I learned quite a bit while working on Harbour Webview demo repo I created, and reviewing the hbhttpd contrib.

I understand that hb_mutexSubscribe() will react on a hb_mutexNotify() or hb_mutexNotifyAll() for the same mutex variable/pointer,
but then what is hb_mutexSubscribeNow(<pMutex>, [<nTimeOut>] [, @<xSubscribed>]), especially since it also has timeout?

Thanks for any help, Eric

[antonio....@gmail.com]

Dear Eric,

Please review this:

https://deepwiki.com/search/i-am-trying-to-prepare-some-mo_b639647c-da9f-4f9e-94e8-704babe9572a

best regards

[antonio....@gmail.com]

Based on the code context, I can explain the difference between hb_mutexSubscribe() and hb_mutexSubscribeNow() in Harbour's multi-threading system.

Understandinghb_mutexSubscribe()vshb_mutexSubscribeNow()

Both functions are part of Harbour's mutex notification system, but they behave differently:

1. hb_mutexSubscribe(<pMutex>, [<nTimeOut>] [, @<xSubscribed>]):
   • This function waits for a notification on the specified mutex.
   • It will block until a notification is received via hb_mutexNotify() or hb_mutexNotifyAll().
   • If a timeout is specified, it will wait only for that duration.
2. hb_mutexSubscribeNow(<pMutex>, [<nTimeOut>] [, @<xSubscribed>]):
   • This function checks if there's already a notification waiting in the queue.
   • It returns immediately if there's a notification already available.
   • If no notification is available, it behaves like hb_mutexSubscribe() - waiting for a notification to arrive.
   • The timeout parameter works the same way as in hb_mutexSubscribe().

The key difference is that hb_mutexSubscribeNow() first checks if there's already a notification in the queue before waiting, making it useful when you want to process any pending notifications without necessarily blocking.

Usage Example

Looking at the code in tests/speedtst.prg, we can see an example of how hb_mutexSubscribe() is used: speedtst.prg:457-460

This code waits for a job notification on the mutex. If the notification value is NIL, it exits the loop.

Implementation in xHarbour Compatibility Layer

The contrib/xhb/hbcompat.ch file shows how these functions are translated for compatibility with xHarbour: hbcompat.ch:152-157 hbcompat.ch:158-163

These translations show that both functions have similar parameters but different behavior. The timeout parameter is converted from milliseconds to seconds when translating from xHarbour to Harbour.

Function Declarations

Both functions are declared in Harbour's core API: harbour.hbx:714-715

And they're also exported in the Harbour DLL: harbour.def:907-908

Practical Use Case

The main practical difference is:

• Use hb_mutexSubscribe() when you want to wait for the next notification.
• Use hb_mutexSubscribeNow() when you want to check if there's already a notification waiting before potentially waiting for a new one.

This is particularly useful in producer-consumer scenarios where you might have multiple notifications queued up and want to process them all without waiting unnecessarily.

Notes

• Both functions are part of Harbour's multi-threading support, which is enabled when the code is compiled with the HB_MT_VM option.
• The timeout parameter in both functions allows you to specify how long to wait for a notification before giving up.
• The @<xSubscribed> parameter is used to receive the value that was passed to hb_mutexNotify() or hb_mutexNotifyAll().
• These functions are essential for inter-thread communication in Harbour applications.

[Eric Lendvai]

Thanks Antonio !

So hb_mutexSubscribeNow() is more like a hb_mutexSubscribeFromNowOn() :)

Eric

> --
> You received this message because you are subscribed to the Google Groups "Harbour Users" group.
> Unsubscribe: harbour-user...@googlegroups.com
> Web: https://groups.google.com/group/harbour-users
> ---
> You received this message because you are subscribed to a topic in the Google Groups "Harbour Users" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/harbour-users/4Y7gx8ZX1fM/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to harbour-user...@googlegroups.com.
> To view this discussion visit https://groups.google.com/d/msgid/harbour-users/7b0d426b-cf79-464e-93d5-6f2792ea3643n%40googlegroups.com.