LEFT | RIGHT |
(no file at all) | |
1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ | |
2 /* | |
3 * Copyright (c) 2010 The Boeing Company | |
4 * | |
5 * This program is free software; you can redistribute it and/or modify | |
6 * it under the terms of the GNU General Public License version 2 as | |
7 * published by the Free Software Foundation; | |
8 * | |
9 * This program is distributed in the hope that it will be useful, | |
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 * GNU General Public License for more details. | |
13 * | |
14 * You should have received a copy of the GNU General Public License | |
15 * along with this program; if not, write to the Free Software | |
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | |
17 * | |
18 * Author: Tom Goff <thomas.goff@boeing.com> | |
19 */ | |
20 | |
21 #ifndef UNIX_FD_READER_H | |
22 #define UNIX_FD_READER_H | |
23 | |
24 #include <stdint.h> | |
25 | |
26 #include "callback.h" | |
27 #include "system-thread.h" | |
28 #include "event-id.h" | |
29 | |
30 /** | |
31 * \file | |
32 * \ingroup system | |
33 * ns3::FdReader declaration. | |
34 */ | |
35 | |
36 namespace ns3 { | |
37 | |
38 /** | |
39 * \ingroup system | |
40 * \brief A class that asynchronously reads from a file descriptor. | |
41 * | |
42 * This class can be used to start a system thread that reads from a | |
43 * given file descriptor and invokes a given callback when data is | |
44 * received. This class handles thread management automatically but | |
45 * the \p DoRead() method must be implemented by a subclass. | |
46 */ | |
47 class FdReader : public SimpleRefCount<FdReader> | |
48 { | |
49 public: | |
50 /** Constructor. */ | |
51 FdReader(); | |
52 /** Destructor. */ | |
53 virtual ~FdReader(); | |
54 | |
55 /** | |
56 * Start a new read thread. | |
57 * | |
58 * \param [in] fd A valid file descriptor open for reading. | |
59 * | |
60 * \param [in] readCallback A callback to invoke when new data is | |
61 * available. | |
62 */ | |
63 void Start (int fd, Callback<void, uint8_t *, ssize_t> readCallback); | |
64 | |
65 /** | |
66 * Stop the read thread and reset internal state. This does not | |
67 * close the file descriptor used for reading. | |
68 */ | |
69 void Stop (void); | |
70 | |
71 protected: | |
72 | |
73 /** | |
74 * \brief A structure representing data read. | |
75 */ | |
76 struct Data | |
77 { | |
78 /** Default constructor, with null buffer and zero length. */ | |
79 Data () : m_buf (0), m_len (0) {} | |
80 /** | |
81 * Construct from a buffer of a given length. | |
82 * | |
83 * \param [in] buf The buffer. | |
84 * \param [in] len The size of the buffer, in bytes. | |
85 */ | |
86 Data (uint8_t *buf, ssize_t len) : m_buf (buf), m_len (len) {} | |
87 /** The read data buffer. */ | |
88 uint8_t *m_buf; | |
89 /** The size of the read data buffer, in bytes. */ | |
90 ssize_t m_len; | |
91 }; | |
92 | |
93 /** | |
94 * \brief The read implementation. | |
95 * | |
96 * The value of \p m_len returned controls further processing. The | |
97 * callback function is only invoked when \p m_len is positive; any | |
98 * data read is not processed when \p m_len is negative; reading | |
99 * stops when \p m_len is zero. | |
100 * | |
101 * The management of memory associated with \p m_buf must be | |
102 * compatible with the read callback. | |
103 * | |
104 * \return A structure representing what was read. | |
105 */ | |
106 virtual FdReader::Data DoRead (void) = 0; | |
107 | |
108 /** | |
109 * \brief The file descriptor to read from. | |
110 */ | |
111 int m_fd; | |
112 | |
113 private: | |
114 | |
115 /** The asynchronous function which performs the read. */ | |
116 void Run (void); | |
117 /** Event handler scheduled for destroy time to halt the thread. */ | |
118 void DestroyEvent (void); | |
119 | |
120 /** The main thread callback function to invoke when we have data. */ | |
121 Callback<void, uint8_t *, ssize_t> m_readCallback; | |
122 ·· | |
123 /** The thread doing the read, created and launched by Start(). */ | |
124 Ptr<SystemThread> m_readThread; | |
125 | |
126 /** Pipe used to signal events between threads. */ | |
127 int m_evpipe[2]; | |
128 /** Signal the read thread to stop. */ | |
129 bool m_stop; | |
130 ·· | |
131 /** | |
132 * The event scheduled for destroy time which will invoke DestroyEvent | |
133 * and halt the thread. | |
134 */ | |
135 EventId m_destroyEvent; | |
136 }; | |
137 | |
138 } // namespace ns3 | |
139 | |
140 #endif /* UNIX_FD_READER_H */ | |
LEFT | RIGHT |