AMX Buffer Manager
K
A
DAK
121
Get Buffer
Once a buffer pool has been created, you may call procedure ajbget to get a buffer from
the pool. The Buffer Manager unlinks a buffer from the pool's free list, sets the
associated buffer use count to one and returns a pointer to the first byte of the buffer.
You may then store and retrieve any data in the buffer as desired.
If there are no free buffers available in the pool when a request to get a buffer from the
pool is made, the Buffer Manager returns an error indication to the caller.
Free Buffer
When the buffer is no longer required, you can call procedure ajbfre to release the
buffer. You indicate the buffer to be released by specifying the pointer to the first byte of
the buffer, the same pointer that was received when you originally acquired the buffer.
The Buffer Manager decrements the use count associated with the buffer by one. If the
use count becomes zero, the buffer is linked to the free list of the pool to which it
belongs.
Use Count
Once you own a buffer, you may call procedure ajbau to increase the use count. Recall
that when a buffer is first obtained, the use count is set to one. If the use count is then
increased by one, the buffer will have to be released twice before it becomes free. In
certain applications such as described in Chapter 9.3, this feature is essential.
Size
You may also call procedure ajbgsz to obtain the size of the buffer. Because the buffer
was obtained from a pool with buffers of known size, this call is usually unnecessary.
However, in applications in which the current owner of a buffer did not actually acquire
the buffer from the Buffer Manager, it is convenient to be able to determine the buffer
size.
Delete
If at some point, there is no longer a need for any of the buffers in the buffer pool, the
entire buffer pool can be deleted with a call to procedure ajbdel. It is your responsibility
to assure that none of the buffers in the pool are still being used at the time you delete the
pool. Once a buffer pool has been deleted, all of the RAM storage provided by you when
the buffer pool was created is available for reuse by the application.
You must be absolutely certain that no task, ISP or Timer Procedure is referencing the
buffer pool just as you go to delete it. Be aware that the deleted buffer pool id may
immediately be reused by AMX for some other purpose.