summaryrefslogtreecommitdiffstats
path: root/ml/dlib/examples/bridge_ex.cpp
blob: bc772ccbb25b7b3c4101533017165969ec64c15d (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
// The contents of this file are in the public domain. See LICENSE_FOR_EXAMPLE_PROGRAMS.txt


/*
    This is an example showing how to use the bridge object from from the 
    dlib C++ Library to send messages via TCP/IP.

    In particular, this example will walk you through four progressively
    more complex use cases of the bridge object.  Note that this example
    program assumes you are already familiar with the pipe object and at
    least the contents of the pipe_ex_2.cpp example program.
*/


// =========== Example program output ===========
/*
     ---- Running example 1 ---- 
    dequeued value: 1
    dequeued value: 2
    dequeued value: 3

     ---- Running example 2 ---- 
    dequeued value: 1
    dequeued value: 2
    dequeued value: 3

     ---- Running example 3 ---- 
    dequeued int:    1
    dequeued int:    2
    dequeued struct: 3   some string

     ---- Running example 4 ---- 
    bridge 1 status: is_connected: true
    bridge 1 status: foreign_ip:   127.0.0.1
    bridge 1 status: foreign_port: 43156
    bridge 2 status: is_connected: true
    bridge 2 status: foreign_ip:   127.0.0.1
    bridge 2 status: foreign_port: 12345
    dequeued int:    1
    dequeued int:    2
    dequeued struct: 3   some string
    bridge 1 status: is_connected: false
    bridge 1 status: foreign_ip:   127.0.0.1
    bridge 1 status: foreign_port: 12345
*/


#include <dlib/bridge.h>
#include <dlib/type_safe_union.h>
#include <iostream>

using namespace dlib;
using namespace std;

// ----------------------------------------------------------------------------------------

void run_example_1();
void run_example_2();
void run_example_3();
void run_example_4();

// ----------------------------------------------------------------------------------------

int main()
{
    run_example_1();
    run_example_2();
    run_example_3();
    run_example_4();
}

// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------

void run_example_1(
)
{
    cout << "\n ---- Running example 1 ---- " << endl;

    /*
        The idea of the bridge is basically to allow two different dlib::pipe objects
        to be connected together via a TCP connection.  This is best illustrated by
        the following short example.  In it we create two pipes, in and out.  When
        an object is enqueued into the out pipe it will be automatically sent 
        through a TCP connection and once received at the other end it will be 
        inserted into the in pipe.
    */
    dlib::pipe<int> in(4), out(4);


    // This bridge will listen on port 12345 for an incoming TCP connection.  Then
    // it will read data from that connection and put it into the in pipe.
    bridge b2(listen_on_port(12345), receive(in));

    // This bridge will initiate a TCP connection and then start dequeuing 
    // objects from out and transmitting them over the connection.
    bridge b1(connect_to_ip_and_port("127.0.0.1", 12345), transmit(out));

    // As an aside, in a real program, each of these bridges and pipes would be in a 
    // separate application.  But to make this example self contained they are both 
    // right here.



    // Now let's put some things into the out pipe
    int value = 1;
    out.enqueue(value);

    value = 2;
    out.enqueue(value);

    value = 3;
    out.enqueue(value);


    // Now those 3 ints can be dequeued from the in pipe.  They will show up
    // in the same order they were inserted into the out pipe.
    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
}

// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------

void run_example_2(
)
{
    cout << "\n ---- Running example 2 ---- " << endl;

    /*
        This example makes a simple echo server on port 12345.  When an object
        is inserted into the out pipe it will be sent over a TCP connection, get 
        put into the echo pipe and then immediately read out of the echo pipe and
        sent back over the TCP connection where it will finally be placed into the in
        pipe.
    */

    dlib::pipe<int> in(4), out(4), echo(4);

    // Just like TCP connections, a bridge can send data both directions.  The directionality
    // of a pipe is indicated by the receive() and transmit() type decorations.  Also, the order
    // they are listed doesn't matter.
    bridge echo_bridge(listen_on_port(12345), receive(echo), transmit(echo));

    // Note that you can also specify the ip and port as a string by using connect_to().
    bridge b1(connect_to("127.0.0.1:12345"), transmit(out), receive(in));


    int value = 1;
    out.enqueue(value);

    value = 2;
    out.enqueue(value);

    value = 3;
    out.enqueue(value);


    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
    in.dequeue(value);
    cout << "dequeued value: "<< value << endl;
}

// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------

struct my_example_object
{
    /*
        All objects passing through a dlib::bridge must be serializable.  This
        means there must exist global functions called serialize() and deserialize()
        which can convert an object into a bit stream and then reverse the process.

        This example object illustrates how this is done.
    */

    int value;
    std::string str;
};

void serialize (const my_example_object& item, std::ostream& out)
{
    /*
        serialize() just needs to write the state of item to the output stream.
        You can do this however you like.  Below, I'm using the serialize functions
        for int and std::string which come with dlib.  But again, you can do whatever
        you want here.
    */
    dlib::serialize(item.value, out);
    dlib::serialize(item.str, out);
}

void deserialize (my_example_object& item, std::istream& in)
{
    /*
        deserialize() is just the inverse of serialize().  Again, you can do
        whatever you want here so long as it correctly reconstructs item.  This
        also means that deserialize() must always consume as many bytes as serialize()
        generates.
    */
    dlib::deserialize(item.value, in);
    dlib::deserialize(item.str, in);
}

// ----------------------------------------------------------------------------------------

void run_example_3(
)
{
    cout << "\n ---- Running example 3 ---- " << endl;

    /*
        In this example we will just send ints and my_example_object objects
        over a TCP connection.  Since we are sending more than one type of
        object through a pipe we will need to use the type_safe_union.
    */

    typedef type_safe_union<int, my_example_object> tsu_type;

    dlib::pipe<tsu_type> in(4), out(4);

    // Note that we don't have to start the listening bridge first.  If b2
    // fails to make a connection it will just keep trying until successful.
    bridge b2(connect_to("127.0.0.1:12345"), receive(in));
    // We don't have to configure a bridge in it's constructor.  If it's 
    // more convenient we can do so by calling reconfigure() instead.
    bridge b1;
    b1.reconfigure(listen_on_port(12345), transmit(out));

    tsu_type msg;

    msg = 1;
    out.enqueue(msg);

    msg = 2;
    out.enqueue(msg);

    msg.get<my_example_object>().value = 3;
    msg.get<my_example_object>().str = "some string";
    out.enqueue(msg);


    // dequeue the three objects we sent and print them on the screen.
    for (int i = 0; i < 3; ++i)
    {
        in.dequeue(msg);
        if (msg.contains<int>())
        {
            cout << "dequeued int:    "<< msg.get<int>() << endl;
        }
        else if (msg.contains<my_example_object>())
        {
            cout << "dequeued struct: "<< msg.get<my_example_object>().value << "   " 
                                       << msg.get<my_example_object>().str << endl;
        }
    }
}

// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------

void run_example_4(
)
{
    cout << "\n ---- Running example 4 ---- " << endl;

    /*
        This final example is the same as example 3 except we will also now be getting 
        status messages from the bridges.  These bridge_status messages tell us the 
        state of the TCP connection associated with a bridge.  Is it connected or not?  
        Who it is connected to?

        The way you get these status messages is by ensuring that your receive pipe is 
        capable of storing bridge_status objects.  If it is then the bridge will 
        automatically insert bridge_status messages into your receive pipe whenever 
        there is a status change. 

        There are only two kinds of status changes.  The establishment of a connection 
        or the closing of a connection.   Also, a connection which closes due to you 
        calling clear(), reconfigure(), or destructing a bridge does not generate a 
        status message since, in this case, you already know about it and just want 
        the bridge to destroy itself as quickly as possible.
    */


    typedef type_safe_union<int, my_example_object, bridge_status> tsu_type;

    dlib::pipe<tsu_type> in(4), out(4);
    dlib::pipe<bridge_status> b1_status(4);

    // setup both bridges to have receive pipes capable of holding bridge_status messages.
    bridge b1(listen_on_port(12345), transmit(out), receive(b1_status));
    // Note that we can also use a hostname with connect_to() instead of supplying an IP address.
    bridge b2(connect_to("localhost:12345"), receive(in));

    tsu_type msg;
    bridge_status bs;

    // Once a connection is established it will generate a status message from each bridge. 
    // Let's get those and print them.  
    b1_status.dequeue(bs);
    cout << "bridge 1 status: is_connected: " << boolalpha << bs.is_connected << endl;
    cout << "bridge 1 status: foreign_ip:   " << bs.foreign_ip << endl;
    cout << "bridge 1 status: foreign_port: " << bs.foreign_port << endl;

    in.dequeue(msg);
    bs = msg.get<bridge_status>();
    cout << "bridge 2 status: is_connected: " << bs.is_connected << endl;
    cout << "bridge 2 status: foreign_ip:   " << bs.foreign_ip << endl;
    cout << "bridge 2 status: foreign_port: " << bs.foreign_port << endl;



    msg = 1;
    out.enqueue(msg);

    msg = 2;
    out.enqueue(msg);

    msg.get<my_example_object>().value = 3;
    msg.get<my_example_object>().str = "some string";
    out.enqueue(msg);


    // Read the 3 things we sent over the connection.
    for (int i = 0; i < 3; ++i)
    {
        in.dequeue(msg);
        if (msg.contains<int>())
        {
            cout << "dequeued int:    "<< msg.get<int>() << endl;
        }
        else if (msg.contains<my_example_object>())
        {
            cout << "dequeued struct: "<< msg.get<my_example_object>().value << "   " 
                                       << msg.get<my_example_object>().str << endl;
        }
    }

    // cause bridge 1 to shutdown completely.  This will close the connection and
    // therefore bridge 2 will generate a status message indicating the connection
    // just closed.
    b1.clear();
    in.dequeue(msg);
    bs = msg.get<bridge_status>();
    cout << "bridge 1 status: is_connected: " << bs.is_connected << endl;
    cout << "bridge 1 status: foreign_ip:   " << bs.foreign_ip << endl;
    cout << "bridge 1 status: foreign_port: " << bs.foreign_port << endl;
}

// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------
// ----------------------------------------------------------------------------------------