Skip to content
This repository
Browse code

Cleaned up queuefile.h javadoc, removed same from queuefile.c

  • Loading branch information...
commit 707752acfb2c6a12d19bcdab7536fc4cf809c56f 1 parent 2622b66
Jochen Bekmann authored October 24, 2012
104  c-tape/queuefile.c
@@ -26,35 +26,9 @@
26 26
 /*
27 27
  * Port of Tape project from Java. https://github.com/square/tape
28 28
  *
29  
- * Original description:
30  
- *
31  
- * A reliable, efficient, file-based, FIFO queue. Additions and removals are
32  
- * O(1). All operations are atomic. Writes are synchronous; data will be written
33  
- * to disk before an operation returns. The underlying file is structured to
34  
- * survive process and even system crashes. If an I/O exception is thrown during
35  
- * a mutating change, the change is aborted. It is safe to continue to use a
36  
- * {@code QueueFile} instance after an exception.
37  
- * <p/>
38  
- * <p>All operations are synchronized. In a traditional queue, the remove
39  
- * operation returns an element. In this queue, {@link #peek} and {@link
40  
- * #remove} are used in conjunction. Use {@code peek} to retrieve the first
41  
- * element, and then {@code remove} to remove it after successful processing. If
42  
- * the system crashes after {@code peek} and during processing, the element will
43  
- * remain in the queue, to be processed when the system restarts.
44  
- * <p/>
45  
- * <p><strong>NOTE:</strong> The current implementation is built
46  
- * for file systems that support atomic segment writes (like YAFFS). Most
47  
- * conventional file systems don't support this; if the power goes out while
48  
- * writing a segment, the segment will contain garbage and the file will be
49  
- * corrupt. We'll add journaling support so this class can be used with more
50  
- * file systems later.
51  
- *
52  
- * @author Bob Lee (bob@squareup.com)
53  
- */
54  
-
55  
-
56  
-/*
57 29
  * Integers are forced to be 32-bit, maximum file size supported is 2^32 (4GB).
  30
+ *
  31
+ * See description in queuefile.h.
58 32
  */
59 33
 
60 34
 /** frees if oldPointer is not NULL, assigns newPointer. */
@@ -79,13 +53,10 @@ static bool _freeAndAssignNonNull(void** oldPointer, void* newPointer);
79 53
 
80 54
 /** A pointer to an element. */
81 55
 typedef struct {
82  
-  
83 56
   /** Position in file. */
84 57
   uint32_t position;
85  
-  
86 58
   /** The length of the data. */
87 59
   uint32_t length;
88  
-  
89 60
 } Element;
90 61
 
91 62
 /**
@@ -94,7 +65,7 @@ typedef struct {
94 65
  * @param position within file
95 66
  * @param length   of data
96 67
  */
97  
-Element* Element_new(uint32_t position, uint32_t length) {
  68
+static Element* Element_new(uint32_t position, uint32_t length) {
98 69
   Element* e = malloc(sizeof(Element));
99 70
   if (CHECKOOM(e)) return NULL;
100 71
   e->position = position;
@@ -102,7 +73,7 @@ Element* Element_new(uint32_t position, uint32_t length) {
102 73
   return e;
103 74
 }
104 75
 
105  
-void Element_fprintf(Element* e, FILE* fout) {
  76
+static void Element_fprintf(Element* e, FILE* fout) {
106 77
   fprintf(fout, "Element:[position = %d, length = %d]",
107 78
           e->position, e->length);
108 79
 }
@@ -166,8 +137,7 @@ struct _QueueFile {
166 137
 static bool initialize(char* filename);
167 138
 static bool QueueFile_readHeader(QueueFile* qf);
168 139
 
169  
-
170  
-// returns NULL on error.
  140
+// see description in queuefile.h.
171 141
 QueueFile* QueueFile_new(char* filename) {
172 142
   if (NULLARG(filename)) return NULL;
173 143
   QueueFile* qf = malloc(sizeof(QueueFile));
@@ -202,6 +172,7 @@ QueueFile* QueueFile_new(char* filename) {
202 172
   return qf;
203 173
 }
204 174
 
  175
+// see description in queuefile.h.
205 176
 bool QueueFile_closeAndFree(QueueFile* qf) {
206 177
   pthread_mutex_lock(&qf->mutex);
207 178
   bool success = !fclose(qf->file);
@@ -410,7 +381,7 @@ static bool QueueFile_ringRead(QueueFile* qf, uint32_t position, byte* buffer,
410 381
   return success;
411 382
 }
412 383
 
413  
-/** Returns true if there are no entries or NULL passed. */
  384
+// see description in queuefile.h.
414 385
 bool QueueFile_isEmpty(QueueFile* qf) {
415 386
   if (NULLARG(qf)) return true;
416 387
   pthread_mutex_lock(&qf->mutex);
@@ -421,13 +392,7 @@ bool QueueFile_isEmpty(QueueFile* qf) {
421 392
 
422 393
 static bool QueueFile_expandIfNecessary(QueueFile* qf, uint32_t dataLength);
423 394
 
424  
-/**
425  
- * Adds an element to the end of the queue.
426  
- *
427  
- * @param data   to copy bytes from
428  
- * @param offset to start from in buffer
429  
- * @param count  number of bytes to copy
430  
- */
  395
+// see description in queuefile.h.
431 396
 bool QueueFile_add(QueueFile* qf, const byte* data, uint32_t offset,
432 397
                    uint32_t count) {
433 398
   if (NULLARG(qf) || NULLARG(data)) return false;
@@ -566,9 +531,7 @@ static bool QueueFile_expandIfNecessary(QueueFile* qf, uint32_t dataLength) {
566 531
   return true;
567 532
 }
568 533
 
569  
-
570  
-/** Reads the eldest element. Returns null if the queue is empty.
571  
- * CALLER MUST FREE THE RETURNED MEMORY */
  534
+// see description in queuefile.h.
572 535
 byte* QueueFile_peek(QueueFile* qf, uint32_t* returnedLength) {
573 536
   if (NULLARG(qf) || NULLARG(returnedLength) || QueueFile_isEmpty(qf)) return NULL;
574 537
   pthread_mutex_lock(&qf->mutex);
@@ -595,19 +558,7 @@ struct _QueueFile_ElementStream {
595 558
   uint32_t remaining;
596 559
 };
597 560
 
598  
-/**
599  
- * Read data from an element stream.
600  
- * @param stream pointer to element stream
601  
- * @param buffer  to copy bytes to
602  
- * @param length  size of buffer
603  
- * @param lengthRemaining will be set to number of bytes left.
604  
- * @return false if an error occurred.
605  
- * *********************************************************
606  
- * WARNING! MUST ONLY BE USED INSIDE A CALLBACK FROM FOREACH
607  
- * as this ensures the queuefile is under mutex lock.
608  
- * the validity of stream is only guaranteed under this callback.
609  
- * *********************************************************
610  
- */
  561
+// see description in queuefile.h.
611 562
 bool QueueFile_readElementStream(QueueFile_ElementStream* stream, byte* buffer,
612 563
                                  uint32_t length, uint32_t* lengthRemaining) {
613 564
   if (NULLARG(stream) || NULLARG(buffer) || NULLARG(lengthRemaining) ||
@@ -628,15 +579,7 @@ bool QueueFile_readElementStream(QueueFile_ElementStream* stream, byte* buffer,
628 579
   return true;
629 580
 }
630 581
 
631  
-/* Reads the next byte, returns as int, or -1 if the element has ended, or there
632  
- * was an error.
633  
- *
634  
- * *********************************************************
635  
- * WARNING! MUST ONLY BE USED INSIDE A CALLBACK FROM FOREACH
636  
- * as this ensures the queuefile is under mutex lock.
637  
- * the validity of stream is only guaranteed under this callback.
638  
- * *********************************************************
639  
- */
  582
+// see description in queuefile.h.
640 583
 int QueueFile_readElementStreamNextByte(QueueFile_ElementStream* stream) {
641 584
   byte buffer;
642 585
   uint32_t remaining;
@@ -650,11 +593,7 @@ int QueueFile_readElementStreamNextByte(QueueFile_ElementStream* stream) {
650 593
   return (int)buffer;
651 594
 }
652 595
 
653  
-/**
654  
- * Invokes the given reader once for the first element in the queue.
655  
- * There will be no callback if the queue is empty.
656  
- * @return false if an error occurred.
657  
- */
  596
+// see description in queuefile.h.
658 597
 bool QueueFile_peekWithElementReader(QueueFile* qf,
659 598
                                      QueueFile_ElementReaderFunc reader) {
660 599
   if (NULLARG(reader) || NULLARG(qf)) return false;
@@ -685,12 +624,7 @@ bool QueueFile_peekWithElementReader(QueueFile* qf,
685 624
   return success;
686 625
 }
687 626
 
688  
-/**
689  
- * Invokes the given reader once for each element in the queue, from eldest to
690  
- * most recently added. Note that this is under lock.
691  
- * There will be no callback if the queue is empty.
692  
- * @return false if an error occurred.
693  
- */
  627
+// see description in queuefile.h.
694 628
 bool QueueFile_forEach(QueueFile* qf, QueueFile_ElementReaderFunc reader) {
695 629
   if (NULLARG(reader) || NULLARG(qf)) return false;
696 630
   pthread_mutex_lock(&qf->mutex);
@@ -730,7 +664,7 @@ bool QueueFile_forEach(QueueFile* qf, QueueFile_ElementReaderFunc reader) {
730 664
   return success;
731 665
 }
732 666
 
733  
-/** Returns the number of elements in this queue, or 0 if NULL is passed. */
  667
+// see description in queuefile.h.
734 668
 uint32_t QueueFile_size(QueueFile* qf) {
735 669
   if (NULLARG(qf)) return 0;
736 670
   pthread_mutex_lock(&qf->mutex);
@@ -739,10 +673,7 @@ uint32_t QueueFile_size(QueueFile* qf) {
739 673
   return elementCount;
740 674
 }
741 675
 
742  
-/**
743  
- * Removes the eldest element.
744  
- * @return false if empty or NULL passed.
745  
- */
  676
+// see description in queuefile.h.
746 677
 bool QueueFile_remove(QueueFile* qf) {
747 678
   if (NULLARG(qf)) return false;
748 679
   pthread_mutex_lock(&qf->mutex);
@@ -776,10 +707,7 @@ bool QueueFile_remove(QueueFile* qf) {
776 707
   return success;
777 708
 }
778 709
 
779  
-/** 
780  
- * Clears this queue. Truncates the file to the initial size.
781  
- * @return false if an error occurred.
782  
- */
  710
+// see description in queuefile.h.
783 711
 bool QueueFile_clear(QueueFile* qf) {
784 712
   if (NULLARG(qf)) return false;
785 713
   bool success = false;
94  c-tape/queuefile.h
@@ -14,6 +14,38 @@
14 14
  * limitations under the License.
15 15
  */
16 16
 
  17
+
  18
+/*
  19
+ * Port of Tape project from Java. https://github.com/square/tape
  20
+ *
  21
+ * Integers are forced to be 32-bit, maximum file size supported is 2^32 (4GB).
  22
+ *
  23
+ * Original description:
  24
+ *
  25
+ * A reliable, efficient, file-based, FIFO queue. Additions and removals are
  26
+ * O(1). All operations are atomic. Writes are synchronous; data will be written
  27
+ * to disk before an operation returns. The underlying file is structured to
  28
+ * survive process and even system crashes. If an I/O exception is thrown during
  29
+ * a mutating change, the change is aborted. It is safe to continue to use a
  30
+ * {@code QueueFile} instance after an exception.
  31
+ *
  32
+ * All operations are synchronized. In a traditional queue, the remove
  33
+ * operation returns an element. In this queue, {@link #peek} and {@link
  34
+ * #remove} are used in conjunction. Use {@code peek} to retrieve the first
  35
+ * element, and then {@code remove} to remove it after successful processing. If
  36
+ * the system crashes after {@code peek} and during processing, the element will
  37
+ * remain in the queue, to be processed when the system restarts.
  38
+ *
  39
+ * NOTE: The current implementation is built
  40
+ * for file systems that support atomic segment writes (like YAFFS). Most
  41
+ * conventional file systems don't support this; if the power goes out while
  42
+ * writing a segment, the segment will contain garbage and the file will be
  43
+ * corrupt. We'll add journaling support so this class can be used with more
  44
+ * file systems later.
  45
+ *
  46
+ */
  47
+
  48
+
17 49
 #ifndef QUEUEFILE_H_
18 50
 #define QUEUEFILE_H_
19 51
 
@@ -22,27 +54,38 @@
22 54
 struct _QueueFile;
23 55
 typedef struct _QueueFile QueueFile;
24 56
 
25  
-// returns NULL on error.
  57
+/** 
  58
+ * Create new queuefile.
  59
+ * @param filename
  60
+ * @return new queuefile or NULL on error. 
  61
+ */
26 62
 QueueFile* QueueFile_new(char* filename);
27 63
 
28  
-/** Closes the underlying file and frees all memory including
29  
- *  the pointer passed. */
  64
+/** 
  65
+ * Closes the underlying file and frees all memory including
  66
+ * the pointer passed.
  67
+ * @param qf queuefile
  68
+ * @return false if an error occurred
  69
+ */
30 70
 bool QueueFile_closeAndFree(QueueFile* qf);
31 71
 
32 72
 /**
33 73
  * Adds an element to the end of the queue.
34  
- *
35  
- * @param data   to copy bytes from
  74
+ * @param qf queuefile
  75
+ * @param data to copy bytes from
36 76
  * @param offset to start from in buffer
37  
- * @param count  number of bytes to copy
38  
- * @returns false if an error occurred
  77
+ * @param count number of bytes to copy
  78
+ * @return false if an error occurred
39 79
  */
40 80
 bool QueueFile_add(QueueFile* qf, const byte* data, uint32_t offset,
41 81
                    uint32_t count);
42 82
 
43  
-/** Reads the eldest element. Returns null if the queue is empty.
  83
+/** 
  84
+ * Reads the eldest element. Returns null if the queue is empty.
  85
+ * @param qf queuefile
44 86
  * @param returnedLength contains the size of the returned buffer.
45  
- * CALLER MUST FREE THE RETURNED MEMORY */
  87
+ * @return element buffer (null if queue is empty) CALLER MUST FREE THIS
  88
+ */
46 89
 byte* QueueFile_peek(QueueFile* qf, uint32_t* returnedLength);
47 90
 
48 91
 
@@ -51,9 +94,9 @@ typedef struct _QueueFile_ElementStream QueueFile_ElementStream;
51 94
 
52 95
 /**
53 96
  * Read data from an element stream.
54  
- * @param stream pointer to element stream
55  
- * @param buffer  to copy bytes to
56  
- * @param length  size of buffer
  97
+ * @param stream pointer to element stream.
  98
+ * @param buffer  to copy bytes to.
  99
+ * @param length  size of buffer.
57 100
  * @param lengthRemaining if not null, will be set to number of bytes left.
58 101
  * @return false if an error occurred.
59 102
  *
@@ -66,8 +109,10 @@ typedef struct _QueueFile_ElementStream QueueFile_ElementStream;
66 109
 bool QueueFile_readElementStream(QueueFile_ElementStream* stream, byte* buffer,
67 110
                                  uint32_t length, uint32_t* lengthRemaining);
68 111
 
69  
-/* Reads the next byte, returns as int, or -1 if the element has ended, or there
70  
- * was an error.
  112
+/**
  113
+ * Reads the next byte.
  114
+ * @param stream pointer to element stream.
  115
+ * @return as int, or -1 if the element has ended, or on error.
71 116
  *
72 117
  * *********************************************************
73 118
  * WARNING! MUST ONLY BE USED INSIDE A CALLBACK FROM FOREACH
@@ -79,25 +124,29 @@ int QueueFile_readElementStreamNextByte(QueueFile_ElementStream* stream);
79 124
 
80 125
 /**
81 126
  * Function which is called by forEach or peekWithElementReader for each element.
  127
+ * @param stream pointer to element stream.
  128
+ * @param remaining number of bytes in element.
82 129
  * @return false to stop the iteration.
83 130
  */
84 131
 typedef bool (*QueueFile_ElementReaderFunc)(QueueFile_ElementStream* stream,
85  
-                                            uint32_t length);
86  
-
  132
+                                            uint32_t remaining);
87 133
 
88 134
 /**
89 135
  * Invokes the given reader once for the first element in the queue.
90 136
  * There will be no callback if the queue is empty.
  137
+ * @param qf queuefile.
  138
+ * @param reader function pointer for callback.
91 139
  * @return false if an error occurred.
92 140
  */
93 141
 bool QueueFile_peekWithElementReader(QueueFile* qf,
94 142
                                      QueueFile_ElementReaderFunc reader);
95 143
 
96  
-
97 144
 /**
98 145
  * Invokes the given reader once for each element in the queue, from eldest to
99 146
  * most recently added. Note that this is under lock.
100 147
  * There will be no callback if the queue is empty.
  148
+ * @param qf queuefile.
  149
+ * @param reader function pointer for callback.
101 150
  * @return false if an error occurred.
102 151
  */
103 152
 bool QueueFile_forEach(QueueFile* qf, QueueFile_ElementReaderFunc reader);
@@ -105,16 +154,23 @@ bool QueueFile_forEach(QueueFile* qf, QueueFile_ElementReaderFunc reader);
105 154
 /** Returns true if there are no entries or NULL passed. */
106 155
 bool QueueFile_isEmpty(QueueFile* qf);
107 156
 
108  
-/** Clears this queue. Truncates the file to the initial size.
  157
+/** 
  158
+ * Clears this queue. Truncates the file to the initial size.
  159
+ * @param qf queuefile.
  160
+ * @param reader function pointer for callback.
109 161
  * @return false if an error occurred.
110 162
  */
111 163
 bool QueueFile_clear(QueueFile* qf);
112 164
 
113  
-/** Returns the number of elements in this queue, or 0 if NULL is passed. */
  165
+/** 
  166
+ * @param qf queuefile.
  167
+ * @return the number of elements in this queue, or 0 if NULL is passed. 
  168
+ */
114 169
 uint32_t QueueFile_size(QueueFile* qf);
115 170
 
116 171
 /**
117 172
  * Removes the eldest element.
  173
+ * @param qf queuefile.
118 174
  * @return false if empty or NULL passed.
119 175
  */
120 176
 bool QueueFile_remove(QueueFile* qf);

0 notes on commit 707752a

Please sign in to comment.
Something went wrong with that request. Please try again.