124
K
A
DAK
AMX Buffer Manager
9.4 Buffer Manager Caveats
Although the Buffer Manager attempts to check as many error conditions as possible, it
cannot protect against a bad system design. However, if a little care is taken during
system design, the Buffer Manager can help make a system more reliable than one that
uses an ad hoc buffer management method.
The most important concept to understand about the Buffer Manager is buffer
ownership. The Buffer Manager owns all free buffers. You must never modify these in
any way.
Once you get a buffer (with a call to the Buffer Manager), you own the buffer. You may
modify the contents of the buffer while it is owned. Once you release the buffer or pass it
to another concurrently executing task or Interrupt Service Procedure, then the buffer is
no longer owned by you and may not be modified or released or have its use count
altered by you in any way.
If the use count is increased by the owner of a buffer, then several simultaneous owners
are allowed. However, when there are several concurrently executing owners, the buffer
content must not be modified unless your design is such that each owner can write to its
own private portion of the buffer. The only permitted operations are reading the buffer
and releasing it. Each owner should either release the buffer or pass the ownership on to
another routine that will release it.
These restrictions are characteristic of message passing between concurrently executing
routines in general, not just of the AMX Buffer Manager. To illustrate the necessity of
these restrictions, a few examples of incorrect usage follow.
1. Task A gets a buffer, fills it, passes it to Task B and releases it. Task B attempts
to use the data in the buffer.
The problem is that Task A released the buffer after it passed ownership to
Task B. Thus Task B will receive a buffer which it does not own. If Task B
modifies the buffer, then the Buffer Manager may produce unpredictable results
the next time it tries to use the buffer.
The solution is to have Task B release the buffer when it is finished with it.
Task B may do this because it owns the buffer after it receives it from Task A.
2. Task A gets a buffer, fills it, passes it to Task B, increments the use count by one
and passes the buffer to task C. Tasks B and C use the buffer and release it.
The problem is that Task A has passed ownership to Task B without first retaining
the ownership by increasing the use count. It then increases the use count of a
buffer it doesn't own. In the meantime, Task B may have finished using the
buffer and released it.
The solution is to have Task A expand the ownership by increasing the use count
before passing the buffer to Task B. Task A then retains one half of the
ownership and may pass this ownership on to Task C.