This article is from the Programming VCOMM FAQ, by email@example.com (Taed Nelson) with numerous contributions by others.
[Contributed by Joe Cossette (firstname.lastname@example.org).]
Basically, due to the type of driver we needed (a virtual COMM port over a
network), we needed to block at times when VCOMM called back on Port
functions. We eventually discovered (painfully...) that for many Port
functions this just wasn't possible. It would initially appear that some
would function OK (you could block), but after a certain number of calls into
it the system would typically hang (stop processing messages).
So we eventually separated the functions into 2 groups (based on looking over
VCOMM docs). The first group was composed of Port functions that could not be
blocked and the second was composed of Port functions that might be a
candidate for blocking.
What follows is the list of Port functions separated into the 2 categories we
eventually came up with (that appeared to work for us). We make no guarantees
on these, not that we've actually blocked on each of the functions listed
(we've blocked on some). Simply, this is the information we've gleaned from
reading the docs and some of our experiences. Maybe others can concur/dispute
these findings and hopefully our cumulative knowledge of VCOMM will increase
by understanding this.
The blockable functions are roughtly the same thing as asynchronous functions,
but I think the VCOMM docs didn't always indicate they were asynchronous.
Sometimes they said they were "safe" (I think???).
Blocking means to block (i.e. put the thread to sleep, typically to be awoken
at some later time). During the blocked period the system runs other threads
(if there're any to run).
The blocking mechanism can be whatever the system might have available to
accomplish this sort of thing (i.e. semaphore, mutex, sleep functions,
7.11.1: Blockable Port functions
7.11.2: Non-Blockable Port functions