| blob | da72938e096fec859a39c6f39da2ffe517beaa61 |
2 /*
3 * libneuro, a light weight abstraction of high or lower libraries
4 * and toolkit for applications.
5 * Copyright (C) 2005-2006 Nicholas Niro, Robert Lemay
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 */
22 #ifndef __EBUF_H
23 #define __EBUF_H
28 /**
29 * @name
30 * Neuro_EBuf
31 *
32 * @description
33 * <h2>IN SHORT :</h2>
34 *
35 * <p>
36 * <i>EBuf</i> stands for Engine Buffer.
37 * Its primary use is to make structures <i>allocation</i>
38 * and <i>reallocation</i> quick and easy; It provides
39 * <i>secure</i> and easy ways to dynamically <i>add</i>,
40 * <i>remove</i> and <i>modify</i> entries from a buffer.
41 * </p>
42 *
43 * <h2>INTRODUCTION :</h2>
44 * <p>
45 * This <i>manual</i> presents the way the module has
46 * to be used (which <i>functions</i> to call and in what order)
47 * <i>briefly</i>,
48 * without going into too much details. The goal of this <i>manual</i>
49 * is to give a general insight as to which functions are
50 * needed to attain a result.
51 * </p>
52 *
53 * <h2>BEGINNING :</h2>
54 * <p>
55 * To make use of even the slightest of this module, the first
56 * requirement is to create a <i>pointer</i> to an EBUF(3) type.
57 * </p>
58 *
59 * <p><i>here's an example</i> : EBUF *abuffer;</p>
60 *
61 * <p>
62 * You cannot use a direct variable like : EBUF abuffer --
63 * for parity reasons(safegard of the data integrity),
64 * the content of the structure is to remain hidden
65 * from external programs.
66 * </p>
67 *
68 * <p>
69 * The EBuf module is completely reentrant, meaning it does
70 * not contain global data in the module, making it
71 * thread safe.
72 * </p>
73 *
74 * <h2>INITIALISING AND FREEING :</h2>
75 *
76 * <p>
77 * Now that the EBUF(3) pointer is created, the next step is to
78 * initialize it by using Neuro_CreateEBuf(3). Among other,
79 * it allocates enough memory for its own internal data and
80 * then resets them to default initial values.
81 * </p>
82 *
83 * <p>
84 * When no longer needed, the pointer should be freed by using
85 * Neuro_CleanEBuf(3). It frees the EBUF(3)'s internal buffer
86 * completely. In the case that the use of the EBUF(3) pointer
87 * is needed after it is freed, the call of Neuro_CreateEBuf(3)
88 * is required again. In the case that just one element
89 * in the buffer needs to be freed, the use of
90 * Neuro_SCleanEBuf(3) is required.
91 * </p>
92 *
93 * <p>
94 * In addition to normal freeing, you can also set a callback
95 * right after the initialization using Neuro_SetcallbEBuf(3).
96 * The callback will be called for every elements that the
97 * EBUF(3) contains right before they are freed (by either calling
98 * Neuro_CleanEBuf(3) or Neuro_SCleanEBuf(3)), permitting
99 * the manual freeing of allocated pointers inside the structure.
100 * Among other, this permits EBUF(3) pointers to contain other
101 * EBUF(3) pointers and/or manually allocated pointers and the
102 * hability to free them cleanly.
103 * </p>
104 *
105 * <p>
106 * <b>NOTE :</b> Neuro_SCleanEBuf(3) <i>doesn't</i> keep the data order in the
107 * buffer at all. It actually is made to break the data order in
108 * order to be more efficient.
109 * </p>
110 *
111 * <p>
112 * <i>here's an example</i>, 3 elements were allocated :
113 * elements 1, 2 and 3. The element number 4 is added to this
114 * buffer to form (1, 2, 3 and 4). The element number 2 is then
115 * removed from the buffer, which would <i>normally</i> do
116 * (1, 3 and 4) <i>but no</i>, this actually does (1, 4 and 3).
117 * </p>
118 *
119 * <p>
120 * The last element is <i>always</i> moved to the position of the
121 * deleted element which actually breaks the order of the data
122 * in the buffer completely (but is necessary for performance reasons).
123 * </p>
124 *
125 * <p>
126 * <i>In order to fix this sorting quirk</i>, all the steps in order to do so
127 * are stated in the <i>MOVING DATA</i> section of this very manual.
128 * </p>
129 *
130 * <h2>ALLOCATING NEW DATA :</h2>
131 *
132 * <p>
133 * by now, we have initalised and possibly set a callback to the
134 * instance, but we are still missing an important step :
135 * creating a structure template which the instance EBUF(3) will
136 * contain. Theres only two ways to allocate : Neuro_AllocEBuf(3)
137 * and Neuro_MultiAllocEBuf(3)
138 * A basic structure template was used in the example in
139 * the man page for the function Neuro_AllocEBuf(3) which is
140 * exactly the function we need to use to allocate a new element.
141 * </p>
142 *
143 *
144 * <h2>READ AND WRITE :</h2>
145 *
146 * <p>
147 * reading/writing from an ebuf element is quite easy, it works kind of
148 * the same as when you call malloc(). After calling Neuro_AllocEBuf(3)
149 * or Neuro_MultiAllocEBuf(3), you can use either Neuro_GiveEBuf(3)
150 * or Neuro_GiveCurEBuf(3). Those two functions return a void pointer
151 * which you simply put into the correct variable. You can then read
152 * or write from the structure directly. If you want to work on all the
153 * data of the buffer, you need to fetch how much elements are contained.
154 * For the purpose the function Neuro_GiveEBufCount(3) has to be used.
155 * Then, when looping, a simple call to Neuro_GiveEBuf(3) has to be used
156 * to get each data structs.
157 * </p>
158 *
159 * <h2>MOVING DATA :</h2>
160 *<p>
161 * on certain occasions, you might want to change the order by which
162 * the data in the EBUF(3) buffer is organised. This is needed when you
163 * want to sort the elements. For this effect, we actually need to use
164 * the function Neuro_SetEBuf(3) to copy a certain element to a
165 * precise address on the buffer. This can't be used directly, we
166 * actually need to get the address of the element we want to change.
167 * To get the address of a certain element, we need to use the function
168 * Neuro_GiveEBufAddr(3).
169 * Here's how we do it :
170 * </p>
171 *
172 * @examples
173 *
174 * -- in this code example, we will transfer the last element into --
175 * -- a certain position in the buffer and transfer that certain --
176 * -- position into the last place. --
177 *
178 * -- ST is a structure we use throughout the EBUF(3) man pages --
179 * -- if you have no idea whats it for, check a few man paged --
180 * -- on EBUF(3), especially the Neuro_SetcallbEBuf(3) one. --
181 * -- we assume this pointer already points to an EBUF(3) element --
182 * ST *element;
183 * u32 elem_value;
184 *
185 * ...
186 *
187 * -- we need the array number of the element to call the next --
188 * -- functions --
189 * if (Neuro_GiveEBufElem(myeng, element, &elem_value))
190 * return; -- an error occured so we bail out --
191 *
192 * -- we then copy the last element into that certain's element address --
193 * Neuro_SetEBuf(myeng, Neuro_GiveEBufAddr(myeng, elem_value), Neuro_GiveCurEBuf(myeng));
194 *
195 * -- now that we copied the address of the last element into --
196 * -- our certain element. we need to copy our certain element into --
197 * -- the last position. --
198 *
199 * Neuro_SetEBuf(myeng, Neuro_GiveEBufAddr(myeng, Neuro_GiveEBufCount(myeng)), element);
200 *
201 * And thats it folks! Now, next time we loop the buffer, the order will have
202 * a certain element at the end and the last element in what ever position our
203 * certain element was.
204 *
205 *
206 * <b>PLEASE NOTE :</b> you <b>can't</b> use the returned value of the function
207 * Neuro_GiveEBufCount(3) to figure if the EBUF(3) is <b>empty</b> (ie when it
208 * doesn't contain any elements or when still unallocated).
209 * <b>for this</b>, you have to use the function Neuro_EBufIsEmpty(3) which returns
210 * 1 if the buffer can <b>not</b> be used and 0 if it <b>can</b>. Any use of an EBUF(3)
211 * which returns 1 when you call Neuro_EBufIsEmpty(3) can create <b>very</b>
212 * unwanted results and <b>very</b> likely cause a segmentation fault.
213 *
214 * @related
215 * EBUF(3), Neuro_CreateEBuf(3), Neuro_SetcallbEBuf(3),
216 * Neuro_AllocEBuf(3), Neuro_MultiAllocEBuf(3),
217 * Neuro_CleanEBuf(3), Neuro_SCleanEBuf(3),
218 * Neuro_GiveEBufCount(3), Neuro_GiveEBufElem(3),
219 * Neuro_GiveCurEBuf(3), Neuro_GiveEBufAddr(3),
220 * Neuro_GiveEBuf(3), Neuro_GiveEBufCore(3),
221 * Neuro_SetEBuf(3), Neuro_CopyEBuf(3),
222 * Neuro_ResetEBuf(3), Neuro_EBufIsEmpty(3)
223 **/
225 /*
226 * This macro is to set the number of extra instances
227 * of memory needs to be allocated per allocations.
228 * In theory, this is absolutely not needed but since
229 * the allocation proccess is slow, the less we do it,
230 * the better. 10 is a good default.
231 */
232 #define MEMORY_ALLOC_OVERH 10
234 #ifdef __cplusplus
236 #endif
238 /**
239 * @description
240 * the Engine Buffer object. A pointer variable
241 * of this type is required.
242 * Example : EBUF *myeng;
243 *
244 * -- this is the struct we want to have buffered,
245 * -- meaning EBUF will keep and create instances of this struct.
246 *
247 * typedef struct ST
248 * {
249 * char *someString;
250 * }ST;
251 */
254 /** Neuro_CreateEBuf
255 * @sdescri
256 * sole constructor of an EBUF element.
257 *
258 * @description
259 * This function initializes and makes operationnal
260 * an EBUF element.
261 *
262 * @param[in]
263 * the address of an EBUF pointer.
264 *
265 * @examples
266 *
267 * static EBUF *myeng;
268 *
269 * ...
270 *
271 * Neuro_CreateEBuf(&myeng);
272 *
273 * ...
274 *
275 * @related
276 * Neuro_CleanEBuf(3), Neuro_CleanEBuf2(3) Neuro_AllocEBuf(3), Neuro_SetcallbEBuf(3),
277 * Neuro_EBufIsEmpty(3)
278 *
279 */
282 /**
283 * @sdescri
284 * creates an useable EBUF element
285 *
286 * @description
287 * This function returns an initialized EBUF elemnt.
288 *
289 * @examples
290 *
291 * static EBUF *myeng;
292 *
293 * ...
294 *
295 * myeng = Neuro_CreateEBuf2();
296 *
297 * ...
298 *
299 * @related
300 * Neuro_CleanEBuf(3), Neuro_CleanEBuf2(3), Neuro_AllocEBuf(3), Neuro_SetcallbEBuf(3),
301 * Neuro_EBufIsEmpty(3)
302 */
305 /** Neuro_SetcallbEBuf
306 * @sdescri
307 * Set a callback that will be called for each array elements
308 * when the EBUF element is cleaning itself after a call to Neuro_CleanEBuf
309 * or Neuro_SCleanEBuf.
310 *
311 * @description
312 * This function is used to set a callback function to the EBUF element.
313 * This callback function will be called (during the cleaning
314 * time) for every arrays right before they are each freed.
315 * This is so you can free custom stuff that you allocated in the
316 * struct you put in EBUF. The callback function will need a single
317 * argument which will be a void pointer. This will point to the
318 * array(single element of the big array) which is being freed.
319 *
320 *
321 * @param[in]
322 * an EBUF pointer.
323 *
324 * @param[in]
325 * a callback which itself contain an argument to a void pointer.
326 *
327 * @examples
328 *
329 * typedef struct ST
330 * {
331 * char *someString;
332 * }ST;
333 *
334 *
335 * static EBUF *myeng;
336 *
337 * static void
338 * callbackclean(void *src)
339 * {
340 * ST *temp;
341 *
342 * temp = (ST*)src;
343 *
344 * if (temp)
345 * {
346 * if (temp->someString)
347 * free(temp->someString);
348 * }
349 * }
350 *
351 * ...
352 *
353 * Neuro_CreateEBuf(&myeng);
354 * Neuro_SetcallbEBuf(myeng, callbackclean);
355 *
356 * ...
357 *
358 * ST *foo;
359 *
360 * Neuro_AllocEBuf(myeng, sizeof(ST*), sizeof(ST));
361 *
362 * foo = Neuro_GiveCurEBuf(myeng);
363 *
364 * foo->someString = (char*)malloc(50);
365 *
366 * ...
367 *
368 * Neuro_CleanEBuf(&myeng);
369 *
370 * @related
371 * Neuro_CreateEBuf(3), Neuro_CleanEBuf(3)
372 *
373 */
376 /** Neuro_AllocEBuf
377 * @sdescri
378 * Simple Allocation and reallocation of an EBuf element.
379 *
380 * @description
381 * This function is pretty much the most useful function in the lot,
382 * it actually creates a new "slot" which can then be used to add
383 * data to an EBUF element. This function and Neuro_MultiAllocEBuf
384 * are the two only functions which allocate/reallocate memory in
385 * an EBUF element.
386 *
387 * Take good note that an EBUF element can buffer
388 * any kinds of structure (so it can dynamically grow easily and avoid memory
389 * leaks). To support this, this function needs only 2 informations
390 * about the structure :
391 * the size of its pointer form and the size of its normal form. It might
392 * also be possible to work with other variable types than structures, although
393 * it is not really recommended unless you know what you are doing.
394 *
395 * @param[in]
396 * an EBUF pointer.
397 *
398 * @param[in]
399 * the size of the pointer form of the structure (usually sizeof can be used to find it).
400 *
401 * @param[in]
402 * the size of the normal form of the structure (usually sizeof can be used to find it).
403 *
404 * @examples
405 * typedef struct ST
406 * {
407 * int foobar;
408 * }ST;
409 *
410 *
411 * static EBUF *myeng;
412 *
413 *
414 * ...
415 *
416 * Neuro_CreateEBuf(&myeng);
417 *
418 * ...
419 *
420 * Neuro_AllocEBuf(myeng, sizeof(ST*), sizeof(ST));
421 *
422 * ...
423 *
424 * Neuro_CleanEBuf(&myeng);
425 *
426 * @related
427 * Neuro_GiveEBufCount(3), Neuro_GiveEBuf(3), Neuro_GiveCurEBuf(3),
428 * Neuro_MultiAllocEBuf(3)
429 */
433 /** Neuro_MultiAllocEBuf
434 * @sdescri
435 * initial allocation of a bigger amount of slots than one.
436 *
437 * @description
438 * This function works exactly the same as Neuro_AllocEBuf except
439 * for one single thing : It can allocate more than one slot at once.
440 * Take very good note that this will only work if the EBUF object hasn't
441 * been allocated before, ie only if it is empty. For security purpose, this
442 * function won't work if theres already allocated slots in the EBUF.
443 *
444 * @param[in]
445 * an EBUF pointer.
446 *
447 * @param[in]
448 * the amount of slots to allocate.
449 *
450 * @param[in]
451 * the size of the pointer form of the structure (usually sizeof can be used to find it).
452 *
453 * @param[in]
454 * the size of the normal form of the structure (usually sizeof can be used to find it).*
455 *
456 * @examples
457 * see the example in Neuro_AllocEBuf(3)
458 *
459 * @related
460 * Neuro_GiveEBufCount(3), Neuro_GiveEBuf(3), Neuro_GiveCurEBuf(3),
461 * Neuro_AllocEBuf(3)
462 */
465 /** Neuro_CleanEBuf
466 * @sdescri
467 * Standard destructor of an EBUF element.
468 *
469 * @description
470 *
471 *
472 * @param[in]
473 * the address of an EBUF pointer.
474 *
475 * @examples
476 *
477 * static EBUF *myeng;
478 *
479 * ...
480 *
481 * Neuro_CreateEBuf(&myeng);
482 *
483 * ...
484 *
485 * Neuro_CleanEBuf(&myeng);
486 *
487 * @related
488 * Neuro_CreateEBuf(3), Neuro_CreateEBuf2(3), Neuro_AllocEBuf(3), Neuro_SetcallbEBuf(3),
489 * Neuro_SCleanEBuf(3)
490 *
491 */
494 /** Neuro_CleanEBuf2
495 * @sdescri
496 * destructor of an EBUF element.
497 *
498 * @description
499 *
500 * @examples
501 *
502 * static EBUF *myeng;
503 *
504 * ...
505 *
506 * myeng = Neuro_CreateEBuf2();
507 *
508 * ...
509 *
510 * Neuro_CleanEBuf2(myeng);
511 * myeng = NULL;
512 *
513 * @related
514 * Neuro_CreateEBuf(3), Neuro_CreateEBuf2(3), Neuro_AllocEBuf(3), Neuro_SetcallbEBuf(3),
515 * Neuro_SCleanEBuf(3)
516 *
517 */
520 /** Neuro_SCleanEBuf
521 * @sdescri
522 * cleans/frees one element.
523 *
524 * @description
525 * This function's purpose is to clean elements in a similar
526 * manner as Neuro_CleanEBuf(3) but it only
527 * cleans one element. Take note that the callback
528 * which can be set using the function Neuro_SetcallbEBuf(3) is also called with this function.
529 *
530 * @param[in]
531 * an EBUF pointer.
532 *
533 * @param[in]
534 * the pointer to an element contained in the EBUF buffer which needs to be cleaned.
535 *
536 * @examples
537 *
538 * typedef struct ST
539 * {
540 * char *someString;
541 * }ST;
542 *
543 * static EBUF *myeng;
544 *
545 * ...
546 *
547 * Neuro_CreateEBuf(&myeng);
548 *
549 * ...
550 *
551 * ST *buf;
552 *
553 * Neuro_AllocEBuf(myeng, sizeof(ST*), sizeof(ST));
554 *
555 * buf = Neuro_GetCurEBuf(myeng);
556 *
557 * buf->someString = "hello";
558 *
559 * -- lets say we no longer need the variable --
560 * -- we can clean it using this function --
561 * Neuro_SCleanEBuf(myeng, buf);
562 *
563 * ...
564 *
565 * Neuro_CleanEBuf(&myeng);
566 *
567 * @related
568 * Neuro_CreateEBuf(3), Neuro_AllocEBuf(3), Neuro_SetcallbEBuf(3), Neuro_CleanEBuf(3), Neuro_GiveEBuf(3), Neuro_GiveCurEBuf(3)
569 *
570 */
573 /** Neuro_GiveEBufCount
574 *
575 * @sdescri
576 * give the count of elements in the array
577 *
578 * @description
579 * This function returns the number of elements contained
580 * in the core buffer. Each elements in the buffer are ordered
581 * in the order they were "pushed" into the buffer thus this
582 * value can be used to loop the buffer for all the elements
583 * one after the other. NOTE This function returns 0 when theres only
584 * one element and it can't return negative values so it cannot
585 * be used to know if the buffer is empty or not! Use the function
586 * Neuro_EBufIsEmpty(3) to check if its empty or not.
587 *
588 * @param[in]
589 * an EBUF pointer.
590 *
591 * @returnval
592 * the amount of elements in the EBUF element.
593 *
594 * @examples
595 *
596 * -- in this example, I ommited the initial creation of the buffer, --
597 * -- the final cleaning of the buffer, --
598 * -- the cleaning callback function, --
599 * -- the allocation of the buffer and --
600 * -- the struct ST and its typedef. --
601 * -- SEE the man page for the function Neuro_AllocEBuf(3) for those --
602 * -- and SEE the man page for Neuro_SetcallbEBuf(3) for the callback --
603 *
604 * ST *buf;
605 * unsigned int total = 0;
606 *
607 * -- we check if the buffer is empty --
608 * if (Neuro_EBufIsEmpty(myeng))
609 * return;
610 *
611 * -- we get the total number of elements in myeng --
612 * -- and also increment it by one because we will --
613 * -- loop the elements from finish to start --
614 * total = Neuro_GiveEBufCount(myeng) + 1;
615 *
616 * while (total-- > 0)
617 * {
618 * buf = Neuro_GiveEBuf(myeng, total);
619 *
620 * ...
621 *
622 * }
623 *
624 * @related
625 * Neuro_AllocEBuf(3), Neuro_GiveEBuf(3),
626 * Neuro_GiveCurEBuf(3), Neuro_EBufIsEmpty(3)
627 */
630 /** Neuro_GiveEBufElem
631 * @sdecri
632 * output the array number of the element object
633 *
634 * @description
635 * This function is used to get the array number
636 * of a structure pointer which is inside
637 * the buffer eng. If the element is not
638 * contained inside the buffer, this will
639 * return 1 and 0 on success. Make sure to
640 * put either a real integer or an allocated
641 * one's address for the *elem argument.
642 *
643 * @param[in]
644 * an EBUF pointer.
645 *
646 * @param[in]
647 * a void pointer of an element
648 * of which the array number will be put
649 * in the output integer.
650 *
651 * @param[out]
652 * the array number of the element in the
653 * void pointer.
654 *
655 * @returnval
656 * either 0 or 1. 1 on error (when the pointer object is not
657 * found in the buffer eng or when the buffer eng is NULL).
658 * 0 on no error.
659 *
660 * @examples
661 *
662 * typedef struct ST
663 * {
664 * char *someString;
665 * }ST;
666 *
667 * -- we create a struct element --
668 * -- called an_element into which --
669 * -- we will put the address of an ebuf allocated element --
670 * -- this method can be used to track certain key elements inside the buffer. --
671 *
672 * static ST *an_element;
673 *
674 * static EBUF *myeng;
675 *
676 * static void
677 * callbackclean(void *src)
678 * {
679 * ST *temp;
680 *
681 * temp = (ST*)src;
682 *
683 * if (temp)
684 * {
685 * if (temp->someString)
686 * free(temp->someString);
687 * }
688 * }
689 *
690 * ...
691 *
692 * Neuro_CreateEBuf(&myeng);
693 * Neuro_SetcallbEBuf(myeng, callbackclean);
694 *
695 * ...
696 *
697 * ST *foo;
698 *
699 * Neuro_AllocEBuf(myeng, sizeof(ST*), sizeof(ST));
700 *
701 * foo = Neuro_GiveCurEBuf(myeng);
702 *
703 *
704 * foo->someString = (char*)malloc(50);
705 *
706 * -- we set our variable to the address that the pointer foo points to --
707 * -- this makes it behave the exact same as if it was actually --
708 * -- the pointer foo... we can then access the data from it --
709 * -- for any purpose and fast. --
710 * an_element = foo;
711 *
712 * ...
713 *
714 * -- in a certain function, we use the content of the pointer an_element --
715 * -- but for certain cases we also need to get its array number. --
716 * -- This only works if this particular pointer was allocated in an EBUF. --
717 *
718 * u32 elem_value = 0;
719 *
720 * if (Neuro_GiveEBufElem(myeng, an_element, &elem_value))
721 * {
722 * printf("an error happened, the element (an_element) wasn't found in the buffer (myeng)\n");
723 * return;
724 * }
725 *
726 * -- now, if there wasn't any errors, the variable an_element --
727 * -- contains the array number for the pointer an_element. --
728 * -- this number can be used with the function Neuro_GiveEBuf(3) or Neuro_GiveEBufAddr(3).
729 *
730 * ...
731 *
732 * Neuro_CleanEBuf(&myeng);
733 *
734 *
735 *
736 * @related
737 * Neuro_GiveEBufAddr(3), Neuro_GiveEBuf(3)
738 */
741 /** Neuro_GiveCurEBuf
742 * @sdescri
743 * outputs the last element of the buffer.
744 *
745 * @description
746 * before this function, we had to get the number of
747 * elements from the buffer using Neuro_GiveEBufCount(3)
748 * and then call Neuro_GiveEBuf(3) to get the element.
749 * Now, this function can be used to have the exact same
750 * result but in just one call.
751 *
752 * @param[in]
753 * an EBUF pointer.
754 *
755 * @returnval
756 * the pointer of the element. It returns NULL on error.
757 *
758 * @examples
759 * -- see the man page for Neuro_GiveEBuf(3) for how this --
760 * -- function can be used. Also, almost all the functions --
761 * -- use this function in their examples so just check how --
762 * -- they use it... usually, this function is called right --
763 * -- after you allocate the buffer using Neuro_AllocEBuf(3), --
764 * -- because we need to get the pointer so we can populate it. --
765 *
766 * @related
767 * Neuro_AllocEBuf(3), Neuro_MultiAllocEBuf(3),
768 * Neuro_GiveEBuf(3)
769 */
772 /** Neuro_GiveEBufAddr
773 *
774 * @sdescri
775 * gives the real address of the element of the array number elem.
776 *
777 * @description
778 * this function is essential in the event that you want
779 * to change the order into which the EBUF buffer is.
780 *
781 * @param[in]
782 * an EBUF pointer.
783 *
784 * @param[in]
785 * the array number of the element you want the pointer address.
786 *
787 * @returnval
788 * the pointer to a pointer which contains the address of the
789 * element's pointer.
790 *
791 * @examples
792 * see the Neuro_EBuf(3) man page on section MOVING DATA for
793 * an example on how to use this function.
794 *
795 * @related
796 * Neuro_GiveEBufElem(3), Neuro_SetEBuf(3),
797 */
800 /** Neuro_GiveEBuf()
801 *
802 * @sdescri
803 * gives the element corresponding to the number input in
804 * elem.
805 *
806 * @description
807 * This function is the default way of getting the
808 * pointer of an allocated element. The pointer can
809 * be used to access the data and read/write to it.
810 *
811 * @param[in]
812 * an EBUF pointer.
813 *
814 * @param[in]
815 * this argument corresponds to the element number
816 * that you want to fetch from the buffer.
817 *
818 * @returnval
819 * the pointer to the element from the EBUF. As a void pointer
820 * so it is possible to "morph" it into any other pointer type.
821 *
822 * @examples
823 *
824 * typedef struct ST
825 * {
826 * char *someString;
827 * }ST;
828 *
829 *
830 * static EBUF *myeng;
831 *
832 * static void
833 * callbackclean(void *src)
834 * {
835 * ST *temp;
836 *
837 * temp = (ST*)src;
838 *
839 * if (temp)
840 * {
841 * if (temp->someString)
842 * free(temp->someString);
843 * }
844 * }
845 *
846 * ...
847 *
848 * Neuro_CreateEBuf(&myeng);
849 * Neuro_SetcallbEBuf(myeng, callbackclean);
850 *
851 * ...
852 *
853 * ST *foo;
854 *
855 * Neuro_AllocEBuf(myeng, sizeof(ST*), sizeof(ST));
856 *
857 * foo = Neuro_GiveCurEBuf(myeng);
858 *
859 * foo->someString = (char*)malloc(50);
860 *
861 * ...
862 *
863 * -- this code outputs to the default output channel --
864 * -- the content of every elements of the buffer --
865 * u32 total = 0;
866 * ST *temp = NULL;
867 *
868 * if (Neuro_EBufIsEmpty(myeng))
869 * return;
870 *
871 * total = Neuro_GiveEBufCount(myeng) + 1;
872 *
873 * while (total-- > 0)
874 * {
875 * temp = Neuro_GiveEBuf(myeng, total);
876 *
877 * printf("some value : %s\n", temp->someString);
878 * }
879 *
880 * ...
881 *
882 * Neuro_CleanEBuf(&myeng);
883 *
884 * @related
885 * Neuro_AllocEBuf(3), Neuro_MultiAllocEBuf(3),
886 * Neuro_GiveEBufCount(3)
887 */
890 /** Neuro_GiveEBufCore
891 * @sdescri
892 * give the core buffer of the EBuf element
893 *
894 * @description
895 * this function should never be used, it returns
896 * the actual pointer of the CORE of an EBUF element.
897 * The need of this function is very close to Nill
898 * and it is strongly advised to avoid the use of this
899 * function at all cost.
900 *
901 * @param[in]
902 * an EBUF pointer.
903 *
904 * @returnval
905 * the CORE of the EBUF's main (and only) buffer.
906 *
907 * @example
908 * this function was initially made for bitmap loading
909 * in neuro extlib, it permitted to input simple string
910 * elements and then the ability to give this core
911 * to the pixmap library so it would load the bitmap
912 * from it. This use was considered a BIG HACK. The neuro
913 * bitmap loading code stopped using this function quite
914 * a long time ago so it is unused anywhere.
915 *
916 * Neuro_SCleanEBuf(3) Neuro_GiveEBufAddr(3)
917 * Neuro_GiveEBufAddr(3), Neuro_SetEBuf(3),
918 * Neuro_CopyEBuf(3), Neuro_ResetEBuf(3)
919 */
923 /** Neuro_SetEBuf
924 *
925 * @sdescri
926 * copy the actual content to another position in the
927 * buffer.
928 *
929 * @description
930 * this function is a key element for the task of sorting
931 * elements among the other elements in the buffer.
932 *
933 * @param[in]
934 * an EBUF pointer.
935 *
936 * @param[in]
937 * the actual address of the pointer of an element from the EBUF.
938 * This informations can ONLY be given by the function
939 * Neuro_GiveEBufAddr(3).
940 *
941 * @param[in]
942 * the pointer of the element to copy to the address to.
943 *
944 * @examples
945 * see the Neuro_EBuf(3) man page on section MOVING DATA for
946 * an example on how to use this function. *
947 *
948 *
949 * Neuro_GiveEBufAddr(3), Neuro_GiveEBufElem(3)
950 */
953 /** Neuro_CopyEBuf
954 * @sdecri
955 * copy the content of an EBUF variable to another EBUF variable.
956 *
957 * @description
958 * nothing unusual with this function, it simply cleanly copies the
959 * content of an already created EBUF element to another one
960 * that wasn't created yet. If copy an EBUF to another that
961 * already contains data, you'll create a big memory leak.
962 * Note : this function is very fast because it is only copies addresses.
963 * Note2 : Also note that only one of the two needs to be cleaned;
964 * they both contain the same addresses.
965 *
966 * @param[in]
967 * an EBUF pointer.
968 *
969 * @param[in]
970 * an EBUF pointer which gets copied into the EBUF to.
971 *
972 * @examples
973 * static EBUF *myeng;
974 *
975 * ...
976 *
977 * Neuro_CreateEBuf(&myeng);
978 *
979 * ...
980 *
981 * EBUF *clone;
982 *
983 * Neuro_CopyEBuf(clone, myeng);
984 *
985 * ...
986 *
987 * Neuro_CleanEBuf(&myeng);
988 *
989 *
990 * @related
991 * Neuro_ResetEBuf(3)
992 */
995 /** Neuro_ResetEBuf
996 * @sdescri
997 * resets the EBUF variable WITHOUT FREEING IT -- Warning this
998 * is a mem leak if you didn't copy the content to another one
999 *
1000 * @description
1001 * use the function Neuro_CopyEBuf(3) to backup the addresses for
1002 * the cleaning process prior to using this function please.
1003 *
1004 * @param[in]
1005 * an EBUF pointer.
1006 *
1007 * @related
1008 * Neuro_CopyEBuf(3)
1009 */
1012 /** Neuro_EBufIsEmpty
1013 * @sdecri
1014 * this is a simple boolean returning function that returns
1015 * 1 if [eng] is empty and 0 if it holds stuff.
1016 *
1017 * @description
1018 * this function is the only way to know if an EBUF is empty
1019 * or not, you CAN'T use the function Neuro_GiveEBufCount(3)
1020 * to figure that.
1021 *
1022 * @param[in]
1023 * an EBUF pointer.
1024 *
1025 * @returnval
1026 * 1 if the EBUF is empty and should not be used and 0 if it
1027 * was created and populated.
1028 *
1029 * @related
1030 * Neuro_GiveEBufCount(3)
1031 */
1034 #ifdef __cplusplus
1035 }
1036 #endif