aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--Doxyfile2
-rw-r--r--src/array.h1
-rw-r--r--src/atom.h1
-rw-r--r--src/client.h3
-rw-r--r--src/doxy/archives.dox9
-rw-r--r--src/doxy/groups.dox19
-rw-r--r--src/doxy/main.dox (renamed from src/main.dox)7
-rw-r--r--src/doxy/servers.dox11
-rw-r--r--src/doxy/streams.dox158
-rw-r--r--src/doxy/threading.dox15
-rw-r--r--src/hash.h1
-rw-r--r--src/ito.h63
-rw-r--r--src/itoatom.h1
-rw-r--r--src/itocondition.h33
-rw-r--r--src/itomutex.h37
-rw-r--r--src/itoqueue.h61
-rw-r--r--src/itoserver.h2
-rw-r--r--src/list.h1
-rw-r--r--src/protocol.h3
-rw-r--r--src/ringbuffer.h3
-rw-r--r--src/server.h2
-rw-r--r--src/serversocket.h3
-rw-r--r--src/set.h1
-rw-r--r--src/socket.h3
-rw-r--r--src/sptr.h3
-rw-r--r--src/tafnode.h13
-rw-r--r--src/tafreader.h1
-rw-r--r--src/tafwriter.h1
-rw-r--r--src/tests/size.cpp13
29 files changed, 375 insertions, 96 deletions
diff --git a/Doxyfile b/Doxyfile
index c3168fa..4e64a4c 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -80,7 +80,7 @@ WARN_LOGFILE = Doxywarn
80#--------------------------------------------------------------------------- 80#---------------------------------------------------------------------------
81# configuration options related to the input files 81# configuration options related to the input files
82#--------------------------------------------------------------------------- 82#---------------------------------------------------------------------------
83INPUT = src 83INPUT = src src/doxy
84FILE_PATTERNS = *.c \ 84FILE_PATTERNS = *.c \
85 *.cc \ 85 *.cc \
86 *.cxx \ 86 *.cxx \
diff --git a/src/array.h b/src/array.h
index 43892ee..75c5dd3 100644
--- a/src/array.h
+++ b/src/array.h
@@ -13,6 +13,7 @@ namespace Bu
13 *@param value (typename) The type of data to store in your list 13 *@param value (typename) The type of data to store in your list
14 *@param valuealloc (typename) Memory Allocator for your value type 14 *@param valuealloc (typename) Memory Allocator for your value type
15 *@param linkalloc (typename) Memory Allocator for the list links. 15 *@param linkalloc (typename) Memory Allocator for the list links.
16 *@ingroup Containers
16 */ 17 */
17 template<typename value, int inc=10, typename valuealloc=std::allocator<value> > 18 template<typename value, int inc=10, typename valuealloc=std::allocator<value> >
18 class Array 19 class Array
diff --git a/src/atom.h b/src/atom.h
index e950a96..1786cf3 100644
--- a/src/atom.h
+++ b/src/atom.h
@@ -9,6 +9,7 @@ namespace Bu
9{ 9{
10 /** 10 /**
11 * 11 *
12 *@ingroup Containers
12 */ 13 */
13 template <typename t, typename talloc=std::allocator<t> > 14 template <typename t, typename talloc=std::allocator<t> >
14 class Atom 15 class Atom
diff --git a/src/client.h b/src/client.h
index 2b7448c..4188a49 100644
--- a/src/client.h
+++ b/src/client.h
@@ -11,7 +11,8 @@ namespace Bu
11 class Socket; 11 class Socket;
12 12
13 /** 13 /**
14 * 14 *@author Mike Buland
15 *@ingroup Serving
15 */ 16 */
16 class Client 17 class Client
17 { 18 {
diff --git a/src/doxy/archives.dox b/src/doxy/archives.dox
new file mode 100644
index 0000000..3b96aa3
--- /dev/null
+++ b/src/doxy/archives.dox
@@ -0,0 +1,9 @@
1/**
2 *@page howto_archives Archiving Your Data a.k.a. Serialization
3 *
4 * Archives are a simple system for providing basic-level data-structure
5 * serialization in a fast and simple manner. They even provide a few more
6 * advanced capabilities for when you need them.
7 *
8 *@todo Finish this page.
9 */
diff --git a/src/doxy/groups.dox b/src/doxy/groups.dox
new file mode 100644
index 0000000..7bff7a7
--- /dev/null
+++ b/src/doxy/groups.dox
@@ -0,0 +1,19 @@
1/**
2 *@defgroup Threading
3 * Threads are awesome.
4 */
5
6/**
7 *@defgroup Serving
8 * Serving data is pretty cool too.
9 */
10
11/**
12 *@defgroup Containers
13 * Containers for data.
14 */
15
16/**
17 *@defgroup Taf
18 * Taf is the best!
19 */
diff --git a/src/main.dox b/src/doxy/main.dox
index 668d2e3..7268890 100644
--- a/src/main.dox
+++ b/src/doxy/main.dox
@@ -7,6 +7,13 @@
7 * cover a wide range of topics from streams and sockets to data structures to 7 * cover a wide range of topics from streams and sockets to data structures to
8 * data serialization and xml handling to threading. 8 * data serialization and xml handling to threading.
9 * 9 *
10 * This documentation is expanding all the time, and should contain
11 * comprehensive guides and API reference, but doesn't yet. For now check out
12 * these sections:
13 * - @ref howto_streams
14 * - @ref howto_archives
15 * - @ref howto_threading
16 * - @ref howto_servers
10 */ 17 */
11 18
12/** 19/**
diff --git a/src/doxy/servers.dox b/src/doxy/servers.dox
new file mode 100644
index 0000000..0ba4bb1
--- /dev/null
+++ b/src/doxy/servers.dox
@@ -0,0 +1,11 @@
1/**
2 *@page howto_servers Creating Internet Servers
3 *
4 * Libbu++ provides a comprehensive set of classes for creating any type of
5 * server that you would like. At the moment these are restricted to using
6 * the Bu::Socket subclass of Bu::Stream, and therefore the INET socket
7 * namespace. This isn't much of a restriction, but hopefully it will be
8 * lifted in the future.
9 *
10 *@todo Finish this page.
11 */
diff --git a/src/doxy/streams.dox b/src/doxy/streams.dox
new file mode 100644
index 0000000..65f01d7
--- /dev/null
+++ b/src/doxy/streams.dox
@@ -0,0 +1,158 @@
1/**
2 *@page howto_streams Working With Streams
3 *
4 * Working with libbu++ streams is simple and very straight-forward, but there
5 * are a few things to understand when you pick them up for the first time.
6 *
7 *@section whatis What is a stream?
8 * A stream is a mechanism that allows data to be transported from one place to
9 * another without interruption and in order. Examples of this include data
10 * being written to a file or being read from a file, data being written to a
11 * network socket or read from a network socket, and so on.
12 * Every type of stream will support a different number of options, for example
13 * file streams are usually seekable, that is, you can select where in the file
14 * you are reading and writing, however network sockets are not seekable. All
15 * of these properties can be determined at runtime through the Stream class.
16 *
17 *@section filters Using filters with streams
18 * Libbu++ supports a special type of Stream that is known as a Filter. Filters
19 * are actually streams, except instead of reading or writing to or from a
20 * file they read or write to or from another stream. This provides a handy
21 * way of chaining any number of filters together along with end-point streams
22 * such as files. One example of this would be applying a BZip2 compression
23 * filter to a file stream to compress all data being written to it.
24 * Once a filter is applied the transformations that it applies to the data will
25 * happen automatically as you use the stream.
26 *
27 * One important thing to remember about streams is that they will commonly
28 * change the options that you have when it comes to interacting with the
29 * stream. This is not a bad thing, it is necesarry, but it is easy to tell
30 * when this is happening. To continue with the above example, you can seek in
31 * a File stream, but not in a BZip2 filtered File stream. This has to do with
32 * the way the compression algorithms work and restrict the operations that can
33 * be easily performed on the data.
34 *
35 * Not all changes that filters apply will be restrictive, filters such as the
36 * Buffer filter will add the ability to seek (to an extent) within the buffered
37 * data.
38 *
39 *@section difference How are libbu++ streams different form stl streams?
40 * While not globally true, many stl streams are designed for formatting the
41 * data that flows through the stream, that means that when you attempt to
42 * write a uint32_t into a standard stream it can be difficult to predict what
43 * the result will be, will it be the binary representation or a textual
44 * conversion?
45 *
46 * Libbu++ streams are very direct about how the data is handled. All end-point
47 * streams will always handle the data that you provide or request without any
48 * modification or formatting, very much like the way libc style file access
49 * works.
50 *
51 * The design of Libbu++ streams was, from the begining, to try to make it as
52 * easy as possible to write general code that was as easy as possible to
53 * extend, and as clear as possible. We have accomplished this by making
54 * streams simple, yet flexible, with a clear API and a flexible filter system
55 * that something geared towards more general formatting, conversion, and
56 * operator-only access can't touch.
57 *
58 *@section usage Using streams directly
59 * To create a stream depends on the type of stream that you're interested in,
60 * each type has it's own constructors designed to create the stream and get
61 * it ready for use. We'll use the Bu::File stream as an example here.
62 *
63 *@code
64 // The constructor and each function call to access the stream could throw
65 // an exception, it's important to catch these and handle them
66 // appropriately.
67 try
68 {
69 // sFileName is a Bu::FString object containing the name of the file to
70 // open, possibly with path elements. The second parameter works like
71 // the fopen mode parameter, and can be "w" for write, "r" for read, or
72 // "a" for append. This will likely be replaced with a bitfield later.
73 Bu::File f( sFileName, "w");
74
75 // At this point we know our file is open, lets write some data to it
76 // The first parameter is a pointer to the data to write, the second is
77 // how many bytes to write.
78 f.write( "Test data, boring old test data.\n", 33 );
79
80 // We don't actually need to close the file explicitly, the
81 // deconstructor will take care of that for us, we could if we wanted
82 // to, simply by calling the f.close() function, but it isn't necesarry.
83 }
84 catch( Bu::FileException &e )
85 {
86 // Here we can report the error to the system, whatever it happened to
87 // be.
88 printf("Error: %s\n", e.what() );
89 }
90 @endcode
91 * This is a most basic example, but it covers all the basics. You don't need
92 * much more than this to write just about any file i/o program, just use the
93 * Bu::Stream::read() and Bu::Stream::write() functions.
94 *
95 * Now lets look at how to add a stream to the mix, we'll BZip2 compress the
96 * above example.
97 *@code
98 // Again, we want to catch exceptions in the entire file handling block.
99 try
100 {
101 // We create the file just like before, nothing different about this.
102 Bu::File f( sFileName, "w");
103
104 // Here, however, we create our Bu::BZip2 object, and pass it a
105 // reference to the file. Now our data will go through Bu::BZip2, then
106 // into Bu::File and onto disk. Notice that you don't have to specify
107 // wether you want to read or write explicitly, the filter can usually
108 // determine this for itself by examining the underlying stream.
109 Bu::BZip2 bz2( f );
110
111 // This is done exactly as before, but this time we write into bz2, not
112 // f. We already know how to do this, because both BZip2 and File
113 // inherit from Bu::Stream, so they both have very similar (if not
114 // identicle) API.
115 bz2.write( "Test data, boring old test data.\n", 33 );
116
117 // Just like last time, we don't have to close either stream explicitly,
118 // they will be destroyed appropriately by the system, and in the
119 // correct order (bz2 first, then f).
120 }
121 catch( Bu::FileException &e )
122 {
123 // Here we can report the error to the system, whatever it happened to
124 // be.
125 printf("Error: %s\n", e.what() );
126 }
127 @endcode
128 *
129 * As you can tell in this example, using streams and filters is very easy to
130 * do, and even makes formerly very complex procedures take almost no time at
131 * all.
132 *
133 *@section usingmore Accepting strings in other classes and functions
134 *
135 * When writing a class or function that uses an already opened stream to read
136 * or write data from or to it's important to plan ahead, and probably accept
137 * an object reference of type Bu::Stream. This makes your code immediately
138 * much more portable, useful, and flexible. You don't have to change anything
139 * about the way you write your class or function, use the standard Bu::Stream
140 * functions like read and write just like before.
141 *
142 * For example, lets say you're creating a new image format, and need to be able
143 * to store images on disk and read them off again, so you write the approprate
144 * file fromat handlers. By using Bu::Stream instead of Bu::File you allow
145 * anyone using your image format to send that data anywhere they would like,
146 * including files, sockets, memory buffers, composite archives, and even
147 * through types of streams that don't exist yet. Not only that, but since
148 * every filter is a stream, anyone is now free to pass you a BZip2 filter or
149 * an encryption filter, or any other chain, so that your data can be
150 * compressed, and possibly encrypted, and sent over the network without any
151 * changes to your original code.
152 *
153 * Understandably you probably want to be sure of a few basics before you go
154 * writing image data to any old stream, such as ensuring the stream supports
155 * writing to begin with. This can be easily handled by taking advantage of
156 * the capability accessors in Bu::Stream, these begin with "can" and "is," see
157 * the documentation for more information.
158 */
diff --git a/src/doxy/threading.dox b/src/doxy/threading.dox
new file mode 100644
index 0000000..0ae5325
--- /dev/null
+++ b/src/doxy/threading.dox
@@ -0,0 +1,15 @@
1/**
2 *@page howto_threading Making Applications Multi-threaded
3 *
4 * Libbu++ provides support for object oriented threading including full support
5 * for inter-thread communication and safety devices such as mutexes,
6 * conditions, and semaphores. It even provides some of the basic foundation
7 * classes in thread-safe versions that often add extra functionality and make
8 * writing thread-safe programs as easy as could be.
9 *
10 * Threads in libbu++ are currently based on the posix model, but will hopefully
11 * adopt other methods behind the scenes for compatability with other operating
12 * systems.
13 *
14 *@todo Finish this page.
15 */
diff --git a/src/hash.h b/src/hash.h
index 4f508b2..62b19c9 100644
--- a/src/hash.h
+++ b/src/hash.h
@@ -165,6 +165,7 @@ namespace Bu
165 *@param keyalloc (typename) Memory allocator for hashtable keys 165 *@param keyalloc (typename) Memory allocator for hashtable keys
166 *@param valuealloc (typename) Memory allocator for hashtable values 166 *@param valuealloc (typename) Memory allocator for hashtable values
167 *@param challoc (typename) Byte allocator for bitflags 167 *@param challoc (typename) Byte allocator for bitflags
168 *@ingroup Containers
168 */ 169 */
169 template<typename key, typename value, typename sizecalc, typename keyalloc, typename valuealloc, typename challoc > 170 template<typename key, typename value, typename sizecalc, typename keyalloc, typename valuealloc, typename challoc >
170 class Hash 171 class Hash
diff --git a/src/ito.h b/src/ito.h
index c062052..4ed2c8b 100644
--- a/src/ito.h
+++ b/src/ito.h
@@ -6,11 +6,12 @@
6namespace Bu 6namespace Bu
7{ 7{
8 /** 8 /**
9 * Simple thread class. This wraps the basic pthread (posix threads) system in 9 * Simple thread class. This wraps the basic pthread (posix threads)
10 * an object oriented sort of way. It allows you to create a class with 10 * system in an object oriented sort of way. It allows you to create a
11 * standard member variables and callable functions that can be run in it's own 11 * class with standard member variables and callable functions that can be
12 * thread, one per class instance. 12 * run in it's own thread, one per class instance.
13 *@author Mike Buland 13 *@author Mike Buland
14 *@ingroup Threading
14 */ 15 */
15 class Ito 16 class Ito
16 { 17 {
@@ -27,24 +28,26 @@ namespace Bu
27 28
28 /** 29 /**
29 * Begin thread execution. This will call the overridden run function, 30 * Begin thread execution. This will call the overridden run function,
30 * which will simply execute in it's own thread until the function exits, 31 * which will simply execute in it's own thread until the function
31 * the thread is killed, or the thread is cancelled (optionally). The 32 * exits, the thread is killed, or the thread is cancelled (optionally).
32 * thread started in this manner has access to all of it's class variables, 33 * The thread started in this manner has access to all of it's class
33 * but be sure to protect possible multiple-access with ItoMutex objects. 34 * variables, but be sure to protect possible multiple-access with
34 *@returns True if starting the thread was successful. False if something 35 * ItoMutex objects.
35 * went wrong and the thread has not started. 36 * @returns True if starting the thread was successful. False if
37 * something went wrong and the thread has not started.
36 */ 38 */
37 bool start(); 39 bool start();
38 40
39 /** 41 /**
40 * Forcibly kill a thread. This is not generally considered a good thing to 42 * Forcibly kill a thread. This is not generally considered a good
41 * do, but in those rare cases you need it, it's invaluable. The problem 43 * thing to do, but in those rare cases you need it, it's invaluable.
42 * with stopping (or killing) a thread is that it stops it the moment you 44 * The problem with stopping (or killing) a thread is that it stops it
43 * call stop, no matter what it's doing. The object oriented approach to 45 * the moment you call stop, no matter what it's doing. The object
44 * this will help clean up any class variables that were used, but anything 46 * oriented approach to this will help clean up any class variables
45 * not managed as a member variable will probably create a memory leak type 47 * that were used, but anything not managed as a member variable will
46 * of situation. Instead of stop, consider using cancel, which can be 48 * probably create a memory leak type of situation. Instead of stop,
47 * handled by the running thread in a graceful manner. 49 * consider using cancel, which can be handled by the running thread in
50 * a graceful manner.
48 *@returns True if the thread was stopped, false otherwise. When this 51 *@returns True if the thread was stopped, false otherwise. When this
49 * function returns the thread may not have stopped, to ensure that the 52 * function returns the thread may not have stopped, to ensure that the
50 * thread has really stopped, call join. 53 * thread has really stopped, call join.
@@ -52,11 +55,11 @@ namespace Bu
52 bool stop(); 55 bool stop();
53 56
54 /** 57 /**
55 * The workhorse of the Ito class. This is the function that will run in 58 * The workhorse of the Ito class. This is the function that will run
56 * the thread, when this function exits the thread dies and is cleaned up 59 * in the thread, when this function exits the thread dies and is
57 * by the system. Make sure to read up on ItoMutex, ItoCondition, and 60 * cleaned up by the system. Make sure to read up on ItoMutex,
58 * cancel to see how to control and protect everything you do in a safe way 61 * ItoCondition, and cancel to see how to control and protect
59 * within this function. 62 * everything you do in a safe way within this function.
60 *@returns I'm not sure right now, but this is the posix standard form. 63 *@returns I'm not sure right now, but this is the posix standard form.
61 */ 64 */
62 virtual void *run()=0; 65 virtual void *run()=0;
@@ -64,13 +67,13 @@ namespace Bu
64 /** 67 /**
65 * Join the thread in action. This function performs what is commonly 68 * Join the thread in action. This function performs what is commonly
66 * called a thread join. That is that it effectively makes the calling 69 * called a thread join. That is that it effectively makes the calling
67 * thread an the Ito thread contained in the called object one in the same, 70 * thread an the Ito thread contained in the called object one in the
68 * and pauses the calling thread until the called thread exits. That is, 71 * same, and pauses the calling thread until the called thread exits.
69 * when called from, say, your main(), mythread.join() will not return until 72 * That is, when called from, say, your main(), mythread.join() will
70 * the thread mythread has exited. This is very handy at the end of 73 * not return until the thread mythread has exited. This is very handy
71 * programs to ensure all of your data was cleaned up. 74 * at the end of programs to ensure all of your data was cleaned up.
72 *@returns True if the thread was joined, false if the thread couldn't be 75 *@returns True if the thread was joined, false if the thread couldn't
73 * joined, usually because it isn't running to begin with. 76 * be joined, usually because it isn't running to begin with.
74 */ 77 */
75 bool join(); 78 bool join();
76 79
diff --git a/src/itoatom.h b/src/itoatom.h
index 7fc9090..2f8ac41 100644
--- a/src/itoatom.h
+++ b/src/itoatom.h
@@ -9,6 +9,7 @@
9/** 9/**
10 * A thread-safe wrapper class. 10 * A thread-safe wrapper class.
11 *@author Mike Buland 11 *@author Mike Buland
12 *@ingroup Threading
12 */ 13 */
13template <class T> 14template <class T>
14class ItoAtom 15class ItoAtom
diff --git a/src/itocondition.h b/src/itocondition.h
index 1793f81..517dd5f 100644
--- a/src/itocondition.h
+++ b/src/itocondition.h
@@ -10,9 +10,9 @@ namespace Bu
10 /** 10 /**
11 * Ito condition. This is a fairly simple condition mechanism. As you may 11 * Ito condition. This is a fairly simple condition mechanism. As you may
12 * notice this class inherits from the ItoMutex class, this is because all 12 * notice this class inherits from the ItoMutex class, this is because all
13 * conditions must be within a locked block. The standard usage of a condition 13 * conditions must be within a locked block. The standard usage of a
14 * is to pause one thread, perhaps indefinately, until another thread signals 14 * condition is to pause one thread, perhaps indefinately, until another
15 * that it is alright to procede. 15 * thread signals that it is alright to procede.
16 * <br> 16 * <br>
17 * Standard usage for the thread that wants to wait is as follows: 17 * Standard usage for the thread that wants to wait is as follows:
18 * <pre> 18 * <pre>
@@ -24,10 +24,11 @@ namespace Bu
24 * ... // Take care of what you have to. 24 * ... // Take care of what you have to.
25 * cond.unlock(); 25 * cond.unlock();
26 * </pre> 26 * </pre>
27 * The usage for the triggering thread is much simpler, when it needs to tell 27 * The usage for the triggering thread is much simpler, when it needs to
28 * the others that it's time to grab some data it calls either signal or 28 * tell the others that it's time to grab some data it calls either signal
29 * broadcast. See both of those functions for the difference. 29 * or broadcast. See both of those functions for the difference.
30 *@author Mike Buland 30 *@author Mike Buland
31 *@ingroup Threading
31 */ 32 */
32 class ItoCondition : public ItoMutex 33 class ItoCondition : public ItoMutex
33 { 34 {
@@ -43,9 +44,9 @@ namespace Bu
43 ~ItoCondition(); 44 ~ItoCondition();
44 45
45 /** 46 /**
46 * Wait forever, or until signalled. This has to be called from within a 47 * Wait forever, or until signalled. This has to be called from within
47 * locked section, i.e. before calling this this object's lock function 48 * a locked section, i.e. before calling this this object's lock
48 * should be called. 49 * function should be called.
49 */ 50 */
50 int wait(); 51 int wait();
51 52
@@ -60,16 +61,18 @@ namespace Bu
60 int wait( int nSec, int nUSec ); 61 int wait( int nSec, int nUSec );
61 62
62 /** 63 /**
63 * Notify the next thread waiting on this condition that they can go ahead. 64 * Notify the next thread waiting on this condition that they can go
64 * This only signals one thread, the next one in the condition queue, that 65 * ahead. This only signals one thread, the next one in the condition
65 * it is safe to procede with whatever operation was being waited on. 66 * queue, that it is safe to procede with whatever operation was being
67 * waited on.
66 */ 68 */
67 int signal(); 69 int signal();
68 70
69 /** 71 /**
70 * Notify all threads waiting on this condition that they can go ahead now. 72 * Notify all threads waiting on this condition that they can go ahead
71 * This function is slower than signal, but more effective in certain 73 * now. This function is slower than signal, but more effective in
72 * situations where you may not know how many threads should be activated. 74 * certain situations where you may not know how many threads should be
75 * activated.
73 */ 76 */
74 int broadcast(); 77 int broadcast();
75 78
diff --git a/src/itomutex.h b/src/itomutex.h
index 9c9d205..27ca125 100644
--- a/src/itomutex.h
+++ b/src/itomutex.h
@@ -7,10 +7,11 @@ namespace Bu
7{ 7{
8 /** 8 /**
9 * Simple mutex wrapper. Currently this doesn't do anything extra for you 9 * Simple mutex wrapper. Currently this doesn't do anything extra for you
10 * except keep all of the functionality together in an OO sorta' way and keep 10 * except keep all of the functionality together in an OO sorta' way and
11 * you from having to worry about cleaning up your mutexes properly, or initing 11 * keep you from having to worry about cleaning up your mutexes properly,
12 * them. 12 * or initing them.
13 *@author Mike Buland 13 *@author Mike Buland
14 *@ingroup Threading
14 */ 15 */
15 class ItoMutex 16 class ItoMutex
16 { 17 {
@@ -23,33 +24,33 @@ namespace Bu
23 /** 24 /**
24 * Destroy a mutex. This can only be done when a mutex is unlocked. 25 * Destroy a mutex. This can only be done when a mutex is unlocked.
25 * Failure to unlock before destroying a mutex object could cause it to 26 * Failure to unlock before destroying a mutex object could cause it to
26 * wait for the mutex to unlock, the odds of which are usually farily low 27 * wait for the mutex to unlock, the odds of which are usually farily
27 * at deconstruction time. 28 * low at deconstruction time.
28 */ 29 */
29 ~ItoMutex(); 30 ~ItoMutex();
30 31
31 /** 32 /**
32 * Lock the mutex. This causes all future calls to lock on this instance 33 * Lock the mutex. This causes all future calls to lock on this
33 * of mutex to block until the first thread that called mutex unlocks it. 34 * instance of mutex to block until the first thread that called mutex
34 * At that point the next thread that called lock will get a chance to go 35 * unlocks it. At that point the next thread that called lock will get
35 * to work. Because of the nature of a mutex lock it is a very bad idea to 36 * a chance to go to work. Because of the nature of a mutex lock it is
36 * do any kind of serious or rather time consuming computation within a 37 * a very bad idea to do any kind of serious or rather time consuming
37 * locked section. This can cause thread-deadlock and your program may 38 * computation within a locked section. This can cause thread-deadlock
38 * hang. 39 * and your program may hang.
39 */ 40 */
40 int lock(); 41 int lock();
41 42
42 /** 43 /**
43 * Unlock the mutex. This allows the next thread that asked for a lock to 44 * Unlock the mutex. This allows the next thread that asked for a lock
44 * lock the mutex and continue with execution. 45 * to lock the mutex and continue with execution.
45 */ 46 */
46 int unlock(); 47 int unlock();
47 48
48 /** 49 /**
49 * Try to lock the mutex. This is the option to go with if you cannot avoid 50 * Try to lock the mutex. This is the option to go with if you cannot
50 * putting lengthy operations within a locked section. trylock will attempt 51 * avoid putting lengthy operations within a locked section. trylock
51 * to lock the mutex, if the mutex is already locked this function returns 52 * will attempt to lock the mutex, if the mutex is already locked this
52 * immediately with an error code. 53 * function returns immediately with an error code.
53 */ 54 */
54 int trylock(); 55 int trylock();
55 56
diff --git a/src/itoqueue.h b/src/itoqueue.h
index 5945344..1a4e0b6 100644
--- a/src/itoqueue.h
+++ b/src/itoqueue.h
@@ -16,6 +16,7 @@ namespace Bu
16 * something is enqueued within the specified time limit, or NULL if the 16 * something is enqueued within the specified time limit, or NULL if the
17 * time limit is exceded. 17 * time limit is exceded.
18 *@author Mike Buland 18 *@author Mike Buland
19 *@ingroup Threading Containers
19 */ 20 */
20 template <class T> 21 template <class T>
21 class ItoQueue 22 class ItoQueue
@@ -59,11 +60,11 @@ namespace Bu
59 } 60 }
60 61
61 /** 62 /**
62 * Enqueue a pieces of data. The new data will go at the end of the queue, 63 * Enqueue a pieces of data. The new data will go at the end of the
63 * and unless another piece of data is enqueued, will be the last piece of 64 * queue, and unless another piece of data is enqueued, will be the
64 * data to be dequeued. 65 * last piece of data to be dequeued.
65 *@param pData The data to enqueue. If this is not a primitive data type 66 *@param pData The data to enqueue. If this is not a primitive data
66 * it's probably best to use a pointer type. 67 * type it's probably best to use a pointer type.
67 */ 68 */
68 void enqueue( T pData ) 69 void enqueue( T pData )
69 { 70 {
@@ -91,20 +92,22 @@ namespace Bu
91 } 92 }
92 93
93 /** 94 /**
94 * Dequeue the first item from the queue. This function can operate in two 95 * Dequeue the first item from the queue. This function can operate in
95 * different modes, blocking and non-blocking. In non-blocking mode it will 96 * two different modes, blocking and non-blocking. In non-blocking
96 * return immediately weather there was data in the queue or not. If there 97 * mode it will return immediately weather there was data in the queue
97 * was data it will remove it from the queue and return it to the caller. 98 * or not. If there was data it will remove it from the queue and
98 * In blocking mode it will block forever wating for data to be enqueued. 99 * return it to the caller.
99 * When data finally is enqueued this function will return immediately with 100 *
100 * the new data. The only way this function should ever return a null in 101 * In blocking mode it will block forever wating for data to be
101 * blocking mode is if the calling thread was cancelled. It's probably a 102 * enqueued. When data finally is enqueued this function will return
102 * good idea to check for NULL return values even if you use blocking, just 103 * immediately with the new data. The only way this function should
103 * to be on the safe side. 104 * ever return a null in blocking mode is if the calling thread was
104 *@param bBlock Set to true to enable blocking, leave as false to work in 105 * cancelled. It's probably a good idea to check for NULL return
105 * non-blocking mode. 106 * values even if you use blocking, just to be on the safe side.
106 *@returns The next piece of data in the queue, or NULL if no data was in 107 *@param bBlock Set to true to enable blocking, leave as false to work
107 * the queue. 108 * in non-blocking mode.
109 *@returns The next piece of data in the queue, or NULL if no data was
110 * in the queue.
108 */ 111 */
109 T dequeue( bool bBlock=false ) 112 T dequeue( bool bBlock=false )
110 { 113 {
@@ -143,15 +146,15 @@ namespace Bu
143 } 146 }
144 147
145 /** 148 /**
146 * Operates just like the other dequeue function in blocking mode with one 149 * Operates just like the other dequeue function in blocking mode with
147 * twist. This function will block for at most nSec seconds and nUSec 150 * one twist. This function will block for at most nSec seconds and
148 * micro-seconds. If the timer is up and no data is available, this will 151 * nUSec micro-seconds. If the timer is up and no data is available,
149 * just return NULL. If data is enqueued before the timeout expires, it 152 * this will just return NULL. If data is enqueued before the timeout
150 * will dequeue and exit immediately. 153 * expires, it will dequeue and exit immediately.
151 *@param nSec The number of seconds to wait, max. 154 *@param nSec The number of seconds to wait, max.
152 *@param nUSec The number of micro-seconds to wait, max. 155 *@param nUSec The number of micro-seconds to wait, max.
153 *@returns The next piece of data in the queue, or NULL if the timeout was 156 *@returns The next piece of data in the queue, or NULL if the timeout
154 * exceeded. 157 * was exceeded.
155 */ 158 */
156 T dequeue( int nSec, int nUSec ) 159 T dequeue( int nSec, int nUSec )
157 { 160 {
@@ -195,9 +198,9 @@ namespace Bu
195 } 198 }
196 199
197 /** 200 /**
198 * Checks to see if the queue has data in it or not. Note that there is no 201 * Checks to see if the queue has data in it or not. Note that there
199 * function to determine the length of the queue. This data isn't kept 202 * is no function to determine the length of the queue. This data
200 * track of. If you really need to know, fix this. 203 * isn't kept track of. If you really need to know, fix this.
201 *@returns True if the queue is empty, false if it has data in it. 204 *@returns True if the queue is empty, false if it has data in it.
202 */ 205 */
203 bool isEmpty() 206 bool isEmpty()
diff --git a/src/itoserver.h b/src/itoserver.h
index 60b15b4..729ae7a 100644
--- a/src/itoserver.h
+++ b/src/itoserver.h
@@ -34,6 +34,8 @@ namespace Bu
34 * In order to use a Server you must subclass it and implement the pure 34 * In order to use a Server you must subclass it and implement the pure
35 * virtual functions. These allow you to receive notification of events 35 * virtual functions. These allow you to receive notification of events
36 * happening within the server itself, and actually makes it useful. 36 * happening within the server itself, and actually makes it useful.
37 *@author Mike Buland
38 *@ingroup Threading Serving
37 */ 39 */
38 class ItoServer : public Ito 40 class ItoServer : public Ito
39 { 41 {
diff --git a/src/list.h b/src/list.h
index ec0c195..8152e6b 100644
--- a/src/list.h
+++ b/src/list.h
@@ -25,6 +25,7 @@ namespace Bu
25 *@param value (typename) The type of data to store in your list 25 *@param value (typename) The type of data to store in your list
26 *@param valuealloc (typename) Memory Allocator for your value type 26 *@param valuealloc (typename) Memory Allocator for your value type
27 *@param linkalloc (typename) Memory Allocator for the list links. 27 *@param linkalloc (typename) Memory Allocator for the list links.
28 *@ingroup Containers
28 */ 29 */
29 template<typename value, typename valuealloc=std::allocator<value>, typename linkalloc=std::allocator<struct ListLink<value> > > 30 template<typename value, typename valuealloc=std::allocator<value>, typename linkalloc=std::allocator<struct ListLink<value> > >
30 class List 31 class List
diff --git a/src/protocol.h b/src/protocol.h
index bca337f..7b69553 100644
--- a/src/protocol.h
+++ b/src/protocol.h
@@ -8,7 +8,8 @@ namespace Bu
8 class Client; 8 class Client;
9 9
10 /** 10 /**
11 * 11 *@author Mike Buland
12 *@ingroup Serving
12 */ 13 */
13 class Protocol 14 class Protocol
14 { 15 {
diff --git a/src/ringbuffer.h b/src/ringbuffer.h
index be80e2f..6a4eecf 100644
--- a/src/ringbuffer.h
+++ b/src/ringbuffer.h
@@ -6,6 +6,9 @@
6 6
7namespace Bu 7namespace Bu
8{ 8{
9 /**
10 *@ingroup Containers
11 */
9 template<typename value, typename valuealloc=std::allocator<value> > 12 template<typename value, typename valuealloc=std::allocator<value> >
10 class RingBuffer 13 class RingBuffer
11 { 14 {
diff --git a/src/server.h b/src/server.h
index 302b6e3..499bf26 100644
--- a/src/server.h
+++ b/src/server.h
@@ -30,6 +30,8 @@ namespace Bu
30 * In order to use a Server you must subclass it and implement the pure 30 * In order to use a Server you must subclass it and implement the pure
31 * virtual functions. These allow you to receive notification of events 31 * virtual functions. These allow you to receive notification of events
32 * happening within the server itself, and actually makes it useful. 32 * happening within the server itself, and actually makes it useful.
33 *@author Mike Buland
34 *@ingroup Serving
33 */ 35 */
34 class Server 36 class Server
35 { 37 {
diff --git a/src/serversocket.h b/src/serversocket.h
index b4ee247..751768d 100644
--- a/src/serversocket.h
+++ b/src/serversocket.h
@@ -15,6 +15,9 @@ namespace Bu
15 * 15 *
16 * Although the accept function returns an integral file descriptor, it is 16 * Although the accept function returns an integral file descriptor, it is
17 * designed to be used with the Socket class. 17 * designed to be used with the Socket class.
18 *
19 *@author Mike Buland
20 *@ingroup Serving
18 */ 21 */
19 class ServerSocket 22 class ServerSocket
20 { 23 {
diff --git a/src/set.h b/src/set.h
index ce2c10a..f35f1f0 100644
--- a/src/set.h
+++ b/src/set.h
@@ -33,6 +33,7 @@ namespace Bu
33 *@param sizecalc (typename) Functor to compute new table size on rehash 33 *@param sizecalc (typename) Functor to compute new table size on rehash
34 *@param keyalloc (typename) Memory allocator for hashtable keys 34 *@param keyalloc (typename) Memory allocator for hashtable keys
35 *@param challoc (typename) Byte allocator for bitflags 35 *@param challoc (typename) Byte allocator for bitflags
36 *@ingroup Containers
36 */ 37 */
37 template<typename key, typename sizecalc, typename keyalloc, typename challoc > 38 template<typename key, typename sizecalc, typename keyalloc, typename challoc >
38 class Set 39 class Set
diff --git a/src/socket.h b/src/socket.h
index d0949cc..95271f8 100644
--- a/src/socket.h
+++ b/src/socket.h
@@ -9,7 +9,8 @@
9namespace Bu 9namespace Bu
10{ 10{
11 /** 11 /**
12 * 12 *@author Mike Buland
13 *@ingroup Serving Streams
13 */ 14 */
14 class Socket : public Stream 15 class Socket : public Stream
15 { 16 {
diff --git a/src/sptr.h b/src/sptr.h
index bccf887..aac7f48 100644
--- a/src/sptr.h
+++ b/src/sptr.h
@@ -9,6 +9,9 @@ namespace Bu
9 template<typename T> class SPtr; 9 template<typename T> class SPtr;
10 template< typename Tb, typename Ta > SPtr<Tb> SPtrCast( SPtr<Ta> src ); 10 template< typename Tb, typename Ta > SPtr<Tb> SPtrCast( SPtr<Ta> src );
11 11
12 /**
13 *@ingroup Containers
14 */
12 template<typename T> 15 template<typename T>
13 class SPtr 16 class SPtr
14 { 17 {
diff --git a/src/tafnode.h b/src/tafnode.h
index 4940bee..585ba73 100644
--- a/src/tafnode.h
+++ b/src/tafnode.h
@@ -10,6 +10,7 @@ namespace Bu
10{ 10{
11 /** 11 /**
12 * 12 *
13 *@ingroup Taf
13 */ 14 */
14 class TafNode 15 class TafNode
15 { 16 {
@@ -33,6 +34,10 @@ namespace Bu
33 34
34 class TafProperty; 35 class TafProperty;
35 class TafComment; 36 class TafComment;
37 /**
38 *
39 *@ingroup Taf
40 */
36 class TafGroup : public TafNode 41 class TafGroup : public TafNode
37 { 42 {
38 public: 43 public:
@@ -68,6 +73,10 @@ namespace Bu
68 NodeList lChildren; 73 NodeList lChildren;
69 }; 74 };
70 75
76 /**
77 *
78 *@ingroup Taf
79 */
71 class TafProperty : public TafNode 80 class TafProperty : public TafNode
72 { 81 {
73 public: 82 public:
@@ -82,6 +91,10 @@ namespace Bu
82 Bu::FString sValue; 91 Bu::FString sValue;
83 }; 92 };
84 93
94 /**
95 *
96 *@ingroup Taf
97 */
85 class TafComment : public TafNode 98 class TafComment : public TafNode
86 { 99 {
87 public: 100 public:
diff --git a/src/tafreader.h b/src/tafreader.h
index eeaafb3..da285ab 100644
--- a/src/tafreader.h
+++ b/src/tafreader.h
@@ -10,6 +10,7 @@ namespace Bu
10{ 10{
11 /** 11 /**
12 * 12 *
13 *@ingroup Taf
13 */ 14 */
14 class TafReader 15 class TafReader
15 { 16 {
diff --git a/src/tafwriter.h b/src/tafwriter.h
index f34395e..3e578d8 100644
--- a/src/tafwriter.h
+++ b/src/tafwriter.h
@@ -10,6 +10,7 @@ namespace Bu
10{ 10{
11 /** 11 /**
12 * 12 *
13 *@ingroup Taf
13 */ 14 */
14 class TafWriter 15 class TafWriter
15 { 16 {
diff --git a/src/tests/size.cpp b/src/tests/size.cpp
new file mode 100644
index 0000000..be13b69
--- /dev/null
+++ b/src/tests/size.cpp
@@ -0,0 +1,13 @@
1#include "bu/hash.h"
2#include "bu/fstring.h"
3
4#define pSize( t ) printf("%15s: %db\n", #t, sizeof( t ) );
5
6int main()
7{
8 typedef Bu::Hash<char, char> charcharHash;
9 typedef Bu::Hash<Bu::FString, Bu::FString> strstrHash;
10 pSize( Bu::FString );
11 pSize( charcharHash );
12 pSize( strstrHash );
13}