|
Check-in Number:
|
2616 | |
| Date: |
2002-Oct-18 14:08:52 (local)
2002-Oct-18 12:08:52 (UTC) |
| User: | rse |
| Branch: | |
| Comment: |
Undocumented internal code is usually always ok (at least as long as it
is self-describing enough ;-), but undocumented internal data is most of
the time nasty. It especially makes it hard to review anything in-depth
because only the author has all of the gory details in mind all the
time. Hence internal data should be documented at least a little bit to
make clear for what each structure member is for. So, here it is. Feel
free to fix my quick descriptions. |
| Tickets: |
|
| Inspections: |
|
| Files: |
|
ossp-pkg/sio/al.c 1.22 -> 1.23
--- al.c 2002/10/18 11:01:59 1.22
+++ al.c 2002/10/18 12:08:52 1.23
@@ -57,39 +57,40 @@
typedef struct al_buffer_st al_buffer_t;
typedef struct {
- void *(*malloc)(size_t);
- void (*free)(void *);
- void *(*balloc)(size_t);
- void (*bfree)(void *);
- size_t new_buffersize;
- int max_freechunks;
+ void *(*malloc)(size_t); /* malloc(3) style function (for al_chunk_t) */
+ void (*free)(void *); /* free(3) style function (for al_chunk_t) */
+ void *(*balloc)(size_t); /* malloc(3) style function (for al_buffer_t) */
+ void (*bfree)(void *); /* free(3) style function (for al_buffer_t) */
+ size_t new_buffersize; /* default size for memory underlying al_buffer_t */
+ int max_freechunks; /* maximum number of cached al_chunk_t objects */
} al_memops_t;
struct al_st {
- LIST(al_chunk_t) chunks;
- size_t bytes;
- al_memops_t m;
+ LIST(al_chunk_t) chunks; /* list header for al_chunk_t objects */
+ size_t bytes; /* total cached number of bytes in chunk */
+ al_memops_t m; /* assembly line memory operations (see above) */
};
struct al_chunk_st {
- NODE(al_chunk_t) chunks;
- al_buffer_t *buf;
- size_t begin, end;
+ NODE(al_chunk_t) chunks; /* list node for al_chunk_t object chaining */
+ al_buffer_t *buf; /* (non-exlusively) referenced buffer object */
+ size_t begin; /* offset into buf->mem where data starts */
+ size_t end; /* offset into buf->mem where data ends */
};
struct al_buffer_st {
- char *mem;
- size_t size;
- int usecount;
- int freemem;
+ char *mem; /* reference to underlying chunk of data */
+ size_t size; /* size of underlying chunk of data */
+ int usecount; /* reference count (from al_chunk_t) */
+ int freemem; /* boolean flag whether chunk of data has to be free(3)ed */
};
struct al_tx_st {
- al_td_t dir;
- al_chunk_t *cur;
- size_t skip;
- size_t togo;
- al_chunk_t view;
+ al_td_t dir; /* traversal direction */
+ al_chunk_t *cur; /* current chunk during traveral steps */
+ size_t skip; /* number of bytes to skip for traversal */
+ size_t togo; /* number of bytes left for traversal */
+ al_chunk_t view; /* synthetic chunk for returning during traversal steps */
};
/* number of bytes described by a chunk */
|
|
