Line data Source code
1 : // Copyright (c) 2012-2021 Made to Order Software Corp. All Rights Reserved
2 : //
3 : // https://snapwebsites.org/project/eventdispatcher
4 : // contact@m2osw.com
5 : //
6 : // This program is free software; you can redistribute it and/or modify
7 : // it under the terms of the GNU General Public License as published by
8 : // the Free Software Foundation; either version 2 of the License, or
9 : // (at your option) any later version.
10 : //
11 : // This program is distributed in the hope that it will be useful,
12 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 : // GNU General Public License for more details.
15 : //
16 : // You should have received a copy of the GNU General Public License along
17 : // with this program; if not, write to the Free Software Foundation, Inc.,
18 : // 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 :
20 : /** \file
21 : * \brief Implementation of the connection base class.
22 : *
23 : * All the connection classes must derive from the connection base
24 : * class.
25 : *
26 : * Connections are able to handle TCP, UDP, Unix signals, etc. The
27 : * base class give us all the necessary defaults for all the connections.
28 : */
29 :
30 :
31 : // self
32 : //
33 : #include "eventdispatcher/connection.h"
34 :
35 : #include "eventdispatcher/communicator.h"
36 : #include "eventdispatcher/exception.h"
37 : #include "eventdispatcher/utils.h"
38 :
39 :
40 : // snaplogger lib
41 : //
42 : #include <snaplogger/message.h>
43 :
44 :
45 : // C++ lib
46 : //
47 : #include <cstring>
48 :
49 :
50 : // C lib
51 : //
52 : #include <sys/ioctl.h>
53 : #include <sys/socket.h>
54 :
55 :
56 : // last include
57 : //
58 : #include <snapdev/poison.h>
59 :
60 :
61 :
62 : namespace ed
63 : {
64 :
65 :
66 :
67 : /** \brief Initializes the connection.
68 : *
69 : * This function initializes a base connection object.
70 : */
71 17 : connection::connection()
72 : {
73 17 : }
74 :
75 :
76 : /** \brief Proceed with the cleanup of the connection.
77 : *
78 : * This function cleans up a connection object.
79 : */
80 17 : connection::~connection()
81 : {
82 17 : }
83 :
84 :
85 : /** \brief Remove this connection from the communicator it was added in.
86 : *
87 : * This function removes the connection from the communicator that
88 : * it was created in.
89 : *
90 : * This happens in several circumstances:
91 : *
92 : * \li When the connection is not necessary anymore
93 : * \li When the connection receives a message saying it should close
94 : * \li When the connection receives a Hang Up event
95 : * \li When the connection looks erroneous
96 : * \li When the connection looks invalid
97 : *
98 : * If the connection is not currently connected to a communicator
99 : * object, then nothing happens.
100 : */
101 2 : void connection::remove_from_communicator()
102 : {
103 2 : communicator::instance()->remove_connection(shared_from_this());
104 2 : }
105 :
106 :
107 : /** \brief Retrieve the name of the connection.
108 : *
109 : * When generating an error or a log the library makes use of this name
110 : * so we actually know which type of socket generated a problem.
111 : *
112 : * \return A constant reference to the connection name.
113 : */
114 20 : std::string const & connection::get_name() const
115 : {
116 20 : return f_name;
117 : }
118 :
119 :
120 : /** \brief Change the name of the connection.
121 : *
122 : * A connection can be given a name. This is mainly for debug purposes.
123 : * We will be adding this name in errors and exceptions as they occur.
124 : *
125 : * The connection makes a copy of \p name.
126 : *
127 : * \param[in] name The name to give this connection.
128 : */
129 15 : void connection::set_name(std::string const & name)
130 : {
131 15 : f_name = name;
132 15 : }
133 :
134 :
135 : /** \brief Tell us whether this socket is a listener or not.
136 : *
137 : * By default a connection object does not represent a listener
138 : * object.
139 : *
140 : * \return The base implementation returns false. Override this
141 : * virtual function if your connection is a listener.
142 : */
143 62 : bool connection::is_listener() const
144 : {
145 62 : return false;
146 : }
147 :
148 :
149 : /** \brief Tell us whether this connection is listening on a Unix signal.
150 : *
151 : * By default a connection object does not represent a Unix signal.
152 : * See the signal implementation for further information about
153 : * Unix signal handling in this library.
154 : *
155 : * \return The base implementation returns false.
156 : */
157 46 : bool connection::is_signal() const
158 : {
159 46 : return false;
160 : }
161 :
162 :
163 : /** \brief Tell us whether this socket is used to receive data.
164 : *
165 : * If you expect to receive data on this connection, then mark it
166 : * as a reader by returning true in an overridden version of this
167 : * function.
168 : *
169 : * \return By default this function returns false (nothing to read).
170 : */
171 27 : bool connection::is_reader() const
172 : {
173 27 : return false;
174 : }
175 :
176 :
177 : /** \brief Tell us whether this socket is used to send data.
178 : *
179 : * If you expect to send data on this connection, then mark it
180 : * as a writer by returning true in an overridden version of
181 : * this function.
182 : *
183 : * \return By default this function returns false (nothing to write).
184 : */
185 44 : bool connection::is_writer() const
186 : {
187 44 : return false;
188 : }
189 :
190 :
191 : /** \brief Check whether the socket is valid for this connection.
192 : *
193 : * Some connections do not make use of a socket so just checking
194 : * whether the socket is -1 is not a good way to know whether the
195 : * socket is valid.
196 : *
197 : * The default function assumes that a socket has to be 0 or more
198 : * to be valid. Other connection implementations may overload this
199 : * function to allow other values.
200 : *
201 : * \return true if the socket is valid.
202 : */
203 23 : bool connection::valid_socket() const
204 : {
205 23 : return get_socket() >= 0;
206 : }
207 :
208 :
209 : /** \brief Check whether this connection is enabled.
210 : *
211 : * It is possible to turn a connection ON or OFF using the set_enable()
212 : * function. This function returns the current value. If true, which
213 : * is the default, the connection is considered enabled and will get
214 : * its callbacks called.
215 : *
216 : * \return true if the connection is currently enabled.
217 : */
218 66 : bool connection::is_enabled() const
219 : {
220 66 : return f_enabled;
221 : }
222 :
223 :
224 : /** \brief Change the status of a connection.
225 : *
226 : * This function let you change the status of a connection from
227 : * enabled (true) to disabled (false) and vice versa.
228 : *
229 : * A disabled connection is not listened on at all. This is similar
230 : * to returning false in all three functions is_listener(),
231 : * is_reader(), and is_writer().
232 : *
233 : * \param[in] enabled The new status of the connection.
234 : */
235 2 : void connection::set_enable(bool enabled)
236 : {
237 2 : f_enabled = enabled;
238 2 : }
239 :
240 :
241 : /** \brief Define the priority of this connection object.
242 : *
243 : * By default connection objects have a priority of 100.
244 : *
245 : * You may also use the set_priority() to change the priority of a
246 : * connection at any time.
247 : *
248 : * \return The current priority of this connection.
249 : *
250 : * \sa set_priority()
251 : */
252 22 : int connection::get_priority() const
253 : {
254 22 : return f_priority;
255 : }
256 :
257 :
258 : /** \brief Change this event priority.
259 : *
260 : * This function can be used to change the default priority (which is
261 : * 100) to a larger or smaller number. A larger number makes the connection
262 : * less important and callbacks get called later. A smaller number makes
263 : * the connection more important and callbacks get called sooner.
264 : *
265 : * Note that the priority of a connection can modified at any time.
266 : * It is not guaranteed to be taken in account immediately, though.
267 : *
268 : * \exception event_dispatcher_parameter_error
269 : * The priority of the event is out of range when this exception is raised.
270 : * The value must between between 0 and EVENT_MAX_PRIORITY. Any
271 : * other value raises this exception.
272 : *
273 : * \param[in] priority Priority of the event.
274 : */
275 0 : void connection::set_priority(priority_t priority)
276 : {
277 0 : if(priority < 0 || priority > EVENT_MAX_PRIORITY)
278 : {
279 0 : std::string err("connection::set_priority(): priority out of range,"
280 0 : " this instance of connection accepts priorities between 0 and ");
281 0 : err += std::to_string(EVENT_MAX_PRIORITY);
282 0 : err += ".";
283 0 : throw event_dispatcher_parameter_error(err);
284 : }
285 :
286 0 : f_priority = priority;
287 :
288 : // make sure that the new order is calculated when we execute
289 : // the next loop
290 : //
291 0 : communicator::instance()->set_force_sort();
292 0 : }
293 :
294 :
295 : /** \brief Less than operator to sort connections by priority.
296 : *
297 : * This function is used to know whether a connection has a higher or lower
298 : * priority. This is used when one adds, removes, or changes the priority
299 : * of a connection. The sorting itself happens in the
300 : * communicator::run() which knows that something changed whenever
301 : * it checks the data.
302 : *
303 : * The result of the priority mechanism is that callbacks of items with
304 : * a smaller priority will be called first.
305 : *
306 : * \param[in] lhs The left hand side connection.
307 : * \param[in] rhs The right hand side connection.
308 : *
309 : * \return true if lhs has a smaller priority than rhs.
310 : */
311 11 : bool connection::compare(pointer_t const & lhs, pointer_t const & rhs)
312 : {
313 11 : return lhs->get_priority() < rhs->get_priority();
314 : }
315 :
316 :
317 : /** \brief Get the number of events a connection will process in a row.
318 : *
319 : * Depending on the connection, their events may get processed within
320 : * a loop. If a new event is received before the current event being
321 : * processed is done, then the system generally processes that new event
322 : * before exiting the loop.
323 : *
324 : * This count limit specifies that a certain amount of events can be
325 : * processed in a row. After that many events were processed, the loop
326 : * exits.
327 : *
328 : * Some loops may not allow for us to immediately quit that function. In
329 : * that case we go on until a breaking point is allowed.
330 : *
331 : * \return The total amount of microsecond allowed before a connection
332 : * processing returns even if additional events are already available
333 : * in connection.
334 : *
335 : * \sa set_event_limit()
336 : */
337 3 : uint16_t connection::get_event_limit() const
338 : {
339 3 : return f_event_limit;
340 : }
341 :
342 :
343 : /** \brief Set the number of events a connection will process in a row.
344 : *
345 : * Depending on the connection, their events may get processed within
346 : * a loop. If a new event is received before the current event being
347 : * processed is done, then the system generally processes that new event
348 : * before exiting the loop.
349 : *
350 : * This count limit specifies that a certain amount of events can be
351 : * processed in a row. After that many events were processed, the loop
352 : * exits.
353 : *
354 : * Some loops may not allow for us to immediately quit that function. In
355 : * that case we go on until a breaking point is allowed.
356 : *
357 : * \param[in] event_limit Number of events to process in a row.
358 : *
359 : * \sa get_event_limit()
360 : */
361 0 : void connection::set_event_limit(uint16_t event_limit)
362 : {
363 0 : f_event_limit = event_limit;
364 0 : }
365 :
366 :
367 : /** \brief Get the processing time limit while processing a connection events.
368 : *
369 : * Depending on the connection, their events may get processed within
370 : * a loop. If a new event is received before the current event being
371 : * processed is done, then the system generally processes that new event
372 : * before exiting the loop.
373 : *
374 : * This count limit specifies that a certain amount of events can be
375 : * processed in a row. After that many events were processed, the loop
376 : * exits.
377 : *
378 : * Some loops may not allow for us to immediately quit that function. In
379 : * that case we go on until a breaking point is allowed.
380 : *
381 : * \return The total amount of microsecond allowed before a connection
382 : * processing returns even if additional events are already available
383 : * in connection.
384 : *
385 : * \sa set_processing_time_limit()
386 : */
387 3 : uint16_t connection::get_processing_time_limit() const
388 : {
389 3 : return f_processing_time_limit;
390 : }
391 :
392 :
393 : /** \brief Set the processing time limit while processing a connection events.
394 : *
395 : * Depending on the connection, their events may get processed within
396 : * a loop. If a new event is received before the current event being
397 : * processed is done, then the system generally processes that new event
398 : * before exiting the loop.
399 : *
400 : * This time limit gives a certain amount of time for a set of events
401 : * to get processed. The default is 0.5 seconds. Note that the system
402 : * won't stop the current event after 0.5 seconds, however, if it
403 : * takes that long or more, then it will not try to process another
404 : * event within that loop before it checks all the connections that
405 : * exist in your process.
406 : *
407 : * Some loops may not allow for us to immediately quit that function. In
408 : * that case we go on until a breaking point is allowed.
409 : *
410 : * \param[in] processing_time_limit The total amount of microsecond
411 : * allowed before a connection processing returns even if
412 : * additional events are already available in connection.
413 : *
414 : * \sa get_processing_time_limit()
415 : */
416 0 : void connection::set_processing_time_limit(std::int32_t processing_time_limit)
417 : {
418 : // in microseconds.
419 : //
420 0 : f_processing_time_limit = processing_time_limit;
421 0 : }
422 :
423 :
424 : /** \brief Return the delay between ticks when this connection times out.
425 : *
426 : * All connections can include a timeout delay in microseconds which is
427 : * used to know when the wait on that specific connection times out.
428 : *
429 : * By default connections do not time out. This function returns -1
430 : * to indicate that this connection does not ever time out. To
431 : * change the timeout delay use the set_timeout_delay() function.
432 : *
433 : * \return This function returns the current timeout delay.
434 : */
435 0 : int64_t connection::get_timeout_delay() const
436 : {
437 0 : return f_timeout_delay;
438 : }
439 :
440 :
441 : /** \brief Change the timeout of this connection.
442 : *
443 : * Each connection can be setup with a timeout in microseconds.
444 : * When that delay is past, the callback function of the connection
445 : * is called with the EVENT_TIMEOUT flag set (note that the callback
446 : * may happen along other events.)
447 : *
448 : * The current date when this function gets called is the starting
449 : * point for each following trigger. Because many other callbacks
450 : * get called, it is not very likely that you will be called
451 : * exactly on time, but the ticks are guaranteed to be requested
452 : * on a non moving schedule defined as:
453 : *
454 : * \f[
455 : * \large tick_i = start-time + k \times delay
456 : * \f]
457 : *
458 : * In other words the time and date when ticks happen does not slip
459 : * with time. However, this implementation may skip one or more
460 : * ticks at any time (especially if the delay is very small).
461 : *
462 : * When a tick triggers an EVENT_TIMEOUT, the communicator::run()
463 : * function calls calculate_next_tick() to calculate the time when
464 : * the next tick will occur which will always be in the function.
465 : *
466 : * \exception event_dispatcher_parameter_error
467 : * This exception is raised if the timeout_us parameter is not considered
468 : * valid. The minimum value is 10 and microseconds. You may use -1 to turn
469 : * off the timeout delay feature.
470 : *
471 : * \param[in] timeout_us The new time out in microseconds.
472 : */
473 1 : void connection::set_timeout_delay(std::int64_t timeout_us)
474 : {
475 1 : if(timeout_us != -1
476 1 : && timeout_us < 10)
477 : {
478 : throw event_dispatcher_parameter_error(
479 : "connection::set_timeout_delay():"
480 : " timeout_us parameter cannot be less than 10"
481 : " unless it is exactly -1, "
482 0 : + std::to_string(timeout_us)
483 0 : + " is not valid.");
484 : }
485 :
486 1 : f_timeout_delay = timeout_us;
487 :
488 : // immediately calculate the next timeout date
489 : //
490 1 : f_timeout_next_date = get_current_date() + f_timeout_delay;
491 1 : }
492 :
493 :
494 : /** \brief Calculate when the next tick shall occur.
495 : *
496 : * This function calculates the date and time when the next tick
497 : * has to be triggered. This function is called after the
498 : * last time the EVENT_TIMEOUT callback was called.
499 : */
500 1 : void connection::calculate_next_tick()
501 : {
502 1 : if(f_timeout_delay == -1)
503 : {
504 : // no delay based timeout so forget about it
505 : //
506 1 : return;
507 : }
508 :
509 : // what is now?
510 : //
511 0 : int64_t const now(get_current_date());
512 :
513 : // gap between now and the last time we triggered this timeout
514 : //
515 0 : int64_t const gap(now - f_timeout_next_date);
516 0 : if(gap < 0)
517 : {
518 : // somehow we got called even though now is still larger
519 : // than f_timeout_next_date
520 : //
521 : // This message happens all the time, it is not helpful at the moment
522 : // so commenting out.
523 : //
524 : //SNAP_LOG_DEBUG
525 : // << "connection::calculate_next_tick()"
526 : // " called even though the next date is still larger than 'now'."
527 : // << SNAP_LOG_SEND;
528 0 : return;
529 : }
530 :
531 : // number of ticks in that gap, rounded up
532 0 : int64_t const ticks((gap + f_timeout_delay - 1) / f_timeout_delay);
533 :
534 : // the next date may be equal to now, however, since it is very
535 : // unlikely that the tick has happened right on time, and took
536 : // less than 1ms, this is rather unlikely all around...
537 : //
538 0 : f_timeout_next_date += ticks * f_timeout_delay;
539 : }
540 :
541 :
542 : /** \brief Return when this connection times out.
543 : *
544 : * All connections can include a timeout in microseconds which is
545 : * used to know when the wait on that specific connection times out.
546 : *
547 : * By default connections do not time out. This function returns -1
548 : * to indicate that this connection does not ever time out. You
549 : * may overload this function to return a different value so your
550 : * version can time out.
551 : *
552 : * \return This function returns the timeout date in microseconds.
553 : */
554 1 : int64_t connection::get_timeout_date() const
555 : {
556 1 : return f_timeout_date;
557 : }
558 :
559 :
560 : /** \brief Change the date at which you want a timeout event.
561 : *
562 : * This function can be used to setup one specific date and time
563 : * at which this connection should timeout. This specific date
564 : * is used internally to calculate the amount of time the poll()
565 : * will have to wait, not including the time it will take
566 : * to execute other callbacks if any needs to be run (i.e. the
567 : * timeout is executed last, after all other events, and also
568 : * priority is used to know which other connections are parsed
569 : * first.)
570 : *
571 : * \exception event_dispatcher_parameter_error
572 : * If the date_us is too small (less than -1) then this exception
573 : * is raised.
574 : *
575 : * \param[in] date_us The new time out in micro seconds.
576 : */
577 2 : void connection::set_timeout_date(std::int64_t date_us)
578 : {
579 2 : if(date_us < -1)
580 : {
581 : throw event_dispatcher_parameter_error(
582 : "connection::set_timeout_date():"
583 : " date_us parameter cannot be less than -1, "
584 0 : + std::to_string(date_us)
585 0 : + " is not valid.");
586 : }
587 :
588 2 : f_timeout_date = date_us;
589 2 : }
590 :
591 :
592 : /** \brief Return when this connection expects a timeout.
593 : *
594 : * All connections can include a timeout specification which is
595 : * either a specific day and time set with set_timeout_date()
596 : * or an repetitive timeout which is defined with the
597 : * set_timeout_delay().
598 : *
599 : * If neither timeout is set the function returns -1. Otherwise
600 : * the function will calculate when the connection is to time
601 : * out and return that date.
602 : *
603 : * If the date is already in the past then the callback
604 : * is called immediately with the EVENT_TIMEOUT flag set.
605 : *
606 : * \note
607 : * If the timeout date is triggered, then the loop calls
608 : * set_timeout_date(-1) because the date timeout is expected
609 : * to only be triggered once. This resetting is done before
610 : * calling the user callback which can in turn set a new
611 : * value back in the connection object.
612 : *
613 : * \return This function returns -1 when no timers are set
614 : * or a timestamp in microseconds when the timer is
615 : * expected to trigger.
616 : */
617 59 : int64_t connection::get_timeout_timestamp() const
618 : {
619 59 : if(f_timeout_date != -1)
620 : {
621 : // this one is easy, it is already defined as expected
622 : //
623 1 : return f_timeout_date;
624 : }
625 :
626 58 : if(f_timeout_delay != -1)
627 : {
628 : // this one makes use of the calculated next date
629 : //
630 0 : return f_timeout_next_date;
631 : }
632 :
633 : // no timeout defined
634 : //
635 58 : return -1;
636 : }
637 :
638 :
639 : /** \brief Save the timeout stamp just before calling poll().
640 : *
641 : * This function is called by the run() function before the poll()
642 : * gets called. It makes sure to save the timeout timestamp so
643 : * when we check the connections again after poll() returns and
644 : * any number of callbacks were called, the timeout does or does
645 : * not happen as expected.
646 : *
647 : * \return The timeout timestamp as returned by get_timeout_timestamp().
648 : *
649 : * \sa get_saved_timeout_timestamp()
650 : * \sa run()
651 : */
652 59 : int64_t connection::save_timeout_timestamp()
653 : {
654 59 : f_saved_timeout_stamp = get_timeout_timestamp();
655 59 : return f_saved_timeout_stamp;
656 : }
657 :
658 :
659 : /** \brief Get the saved timeout timestamp.
660 : *
661 : * This function returns the timeout as saved by the
662 : * save_timeout_timestamp() function. The timestamp returned by
663 : * this function was frozen so if the user calls various timeout
664 : * functions that could completely change the timeout stamp that
665 : * the get_timeout_timestamp() would return just at the time we
666 : * want to know whether th timeout callback needs to be called
667 : * will be ignored by the loop.
668 : *
669 : * \return The saved timeout stamp as returned by save_timeout_timestamp().
670 : *
671 : * \sa save_timeout_timestamp()
672 : * \sa run()
673 : */
674 59 : int64_t connection::get_saved_timeout_timestamp() const
675 : {
676 59 : return f_saved_timeout_stamp;
677 : }
678 :
679 :
680 : /** \brief Make this connection socket a non-blocking socket.
681 : *
682 : * For the read and write to work as expected we generally need
683 : * to make those sockets non-blocking.
684 : *
685 : * For accept(), you do just one call and return and it will not
686 : * block on you. It is important to not setup a socket you
687 : * listen on as non-blocking if you do not want to risk having the
688 : * accepted sockets non-blocking.
689 : *
690 : * \param[in] non_blocking_socket Make socket non-block if true,
691 : * blocking if false.
692 : */
693 4 : void connection::non_blocking() const
694 : {
695 8 : if(valid_socket()
696 4 : && get_socket() >= 0)
697 : {
698 4 : int optval(1);
699 4 : ioctl(get_socket(), FIONBIO, &optval);
700 : }
701 4 : }
702 :
703 :
704 : /** \brief Ask the OS to keep the socket alive.
705 : *
706 : * This function marks the socket with the SO_KEEPALIVE flag. This means
707 : * the OS implementation of the network stack should regularly send
708 : * small messages over the network to keep the connection alive.
709 : *
710 : * The function returns whether the function works or not. If the function
711 : * fails, it logs a warning and returns.
712 : */
713 0 : void connection::keep_alive() const
714 : {
715 0 : if(get_socket() != -1)
716 : {
717 0 : int optval(1);
718 0 : socklen_t const optlen(sizeof(optval));
719 0 : if(setsockopt(get_socket(), SOL_SOCKET, SO_KEEPALIVE, &optval, optlen) != 0)
720 : {
721 0 : int const e(errno);
722 0 : SNAP_LOG_WARNING
723 0 : << "connection::keep_alive(): error "
724 : << e
725 : << " ("
726 0 : << strerror(e)
727 : << ") occurred trying to mark socket with SO_KEEPALIVE."
728 : << SNAP_LOG_SEND;
729 : }
730 : }
731 0 : }
732 :
733 :
734 : /** \brief Lets you know whether mark_done() was called.
735 : *
736 : * This function returns true if mark_done() was called on this connection.
737 : */
738 1 : bool connection::is_done() const
739 : {
740 1 : return f_done;
741 : }
742 :
743 :
744 : /** \brief Call once you are done with a connection.
745 : *
746 : * This function lets the connection know that you are done with it.
747 : * It is very important to call this function before you send the last
748 : * message. For example, with its permanent connection the snapbackend
749 : * tool does this:
750 : *
751 : * \code
752 : * f_messenger->mark_done();
753 : * f_messenger->send_message(stop_message);
754 : * \endcode
755 : *
756 : * The f_done flag is currently used in two situations by the main
757 : * system:
758 : *
759 : * \li write buffer is empty
760 : *
761 : * There are times when you send one or more last messages to a connection.
762 : * The write is generally buffered and will be processed whenever you
763 : * next come back in the run() loop.
764 : *
765 : * So one knows that the write (output) buffer is empty whenever one gets
766 : * its process_empty_buffer() callback called. At that point, the connection
767 : * can be removed from the communicator instance since we are done with
768 : * it. The default process_empty_buffer() does that for us whenever the
769 : * mark_done() function was called.
770 : *
771 : * \li HUP of a permanent connection
772 : *
773 : * When the f_done flag is set, the next HUP error is properly interpreted
774 : * as "we are done". Otherwise, a HUP is interpreted as a lost connection
775 : * and since a permanent connection is... permanent, it simply restarts the
776 : * connect process to reconnect to the server.
777 : *
778 : * \todo
779 : * Since we remove the connection on a process_empty_buffer(), maybe we
780 : * should have the has_output() as a virtual function and if it returns
781 : * true (which would be the default,) then we should remove the connection
782 : * immediately since it is already done? This may require a quick review
783 : * since in some cases we are not to remove the connection at all. But
784 : * this function could call the process_empty_buffer(), which can be
785 : * overridden so the developer can add its own callback to avoid the
786 : * potential side effect.
787 : *
788 : * \sa is_done()
789 : * \sa mark_not_done()
790 : */
791 2 : void connection::mark_done()
792 : {
793 2 : f_done = true;
794 :
795 : //if(!has_output())
796 : //{
797 : // process_empty_buffer();
798 : //}
799 2 : }
800 :
801 :
802 : /** \brief Mark this connection as not done.
803 : *
804 : * In some cases you may want to mark a connection as done and later
805 : * restore it as not done.
806 : *
807 : * Specifically, this is used by the
808 : * tcp_blocking_client_message_connection class. When you call the
809 : * run() function, this mark_not_done() function gets called so in
810 : * effect you can re-enter the run() loop multiple times. Each time,
811 : * you have to call the mark_done() function to exit the loop.
812 : *
813 : * \sa is_done()
814 : * \sa mark_done()
815 : */
816 0 : void connection::mark_not_done()
817 : {
818 0 : f_done = false;
819 0 : }
820 :
821 :
822 : /** \brief This callback gets called whenever the connection times out.
823 : *
824 : * This function is called whenever a timeout is detected on this
825 : * connection. It is expected to be overwritten by your class if
826 : * you expect to use the timeout feature.
827 : *
828 : * The timer class is expected to always have a timer (although
829 : * the connection can temporarily be disabled) which triggers this
830 : * callback on a given periodicity.
831 : */
832 0 : void connection::process_timeout()
833 : {
834 0 : }
835 :
836 :
837 : /** \brief This callback gets called whenever the signal happened.
838 : *
839 : * This function is called whenever a certain signal (as defined in
840 : * your signal object) was detected while waiting for an
841 : * event.
842 : */
843 0 : void connection::process_signal()
844 : {
845 0 : }
846 :
847 :
848 : /** \brief This callback gets called whenever data can be read.
849 : *
850 : * This function is called whenever a socket has data that can be
851 : * read. For UDP, this means reading one packet. For TCP, it means
852 : * you can read at least one byte. To avoid blocking in TCP,
853 : * you must have called the non_blocking() function on that
854 : * connection, then you can attempt to read as much data as you
855 : * want.
856 : */
857 8 : void connection::process_read()
858 : {
859 8 : }
860 :
861 :
862 : /** \brief This callback gets called whenever data can be written.
863 : *
864 : * This function is called whenever a socket has space in its output
865 : * buffers to write data there.
866 : *
867 : * For UDP, this means writing one packet.
868 : *
869 : * For TCP, it means you can write at least one byte. To be able to
870 : * write as many bytes as you want, you must make sure to make the
871 : * socket non_blocking() first, then you can write as many bytes as
872 : * you want, although all those bytes may not get written in one
873 : * go (you may need to wait for the next call to this function to
874 : * finish up your write.)
875 : */
876 3 : void connection::process_write()
877 : {
878 3 : }
879 :
880 :
881 : /** \brief Sent all data to the other end.
882 : *
883 : * This function is called whenever a connection bufferized data
884 : * to be sent to the other end of the connection and that buffer
885 : * just went empty.
886 : *
887 : * Just at the time the function gets called, the buffer is empty.
888 : * You may refill it at that time.
889 : *
890 : * The callback is often used to remove a connection from the
891 : * communicator instance (i.e. just after we sent a last
892 : * message to the other end.)
893 : *
894 : * By default this function removes the connection from the
895 : * communicator instance if the mark_done() function was
896 : * called. Otherwise, it just ignores the message.
897 : */
898 5 : void connection::process_empty_buffer()
899 : {
900 5 : if(f_done)
901 : {
902 4 : SNAP_LOG_DEBUG
903 2 : << "socket "
904 2 : << get_socket()
905 : << " of connection \""
906 : << f_name
907 : << "\" was marked as done, removing in process_empty_buffer()."
908 : << SNAP_LOG_SEND;
909 :
910 2 : remove_from_communicator();
911 : }
912 5 : }
913 :
914 :
915 : /** \brief This callback gets called whenever a connection is made.
916 : *
917 : * A listening server receiving a new connection gets this function
918 : * called. The function is expected to create a new connection object
919 : * and add it to the communicator.
920 : *
921 : * \code
922 : * // get the socket from the accept() function
923 : * int const client_socket(accept());
924 : * client_impl::pointer_t connection(std::make_shared<client_impl>(get_communicator(), client_socket));
925 : * connection->set_name("connection created by server on accept()");
926 : * get_communicator()->add_connection(connection);
927 : * \endcode
928 : */
929 0 : void connection::process_accept()
930 : {
931 0 : }
932 :
933 :
934 : /** \brief This callback gets called whenever an error is detected.
935 : *
936 : * If an error is detected on a socket, this callback function gets
937 : * called. By default the function removes the connection from
938 : * the communicator because such errors are generally non-recoverable.
939 : *
940 : * The function also logs an error message.
941 : */
942 0 : void connection::process_error()
943 : {
944 : // TBD: should we offer a virtual close() function to handle this
945 : // case? because the get_socket() function will not return
946 : // -1 after such errors...
947 :
948 0 : if(get_socket() == -1)
949 : {
950 0 : SNAP_LOG_DEBUG
951 0 : << "socket "
952 0 : << get_socket()
953 : << " of connection \""
954 : << f_name
955 : << "\" was marked as erroneous by the kernel or was closed (-1)."
956 : << SNAP_LOG_SEND;
957 : }
958 : else
959 : {
960 : // this happens all the time, so we changed the WARNING into a
961 : // DEBUG, too much logs by default otherwise...
962 : //
963 0 : SNAP_LOG_DEBUG
964 0 : << "socket "
965 0 : << get_socket()
966 : << " of connection \""
967 : << f_name
968 : << "\" was marked as erroneous by the kernel."
969 : << SNAP_LOG_SEND;
970 : }
971 :
972 0 : remove_from_communicator();
973 0 : }
974 :
975 :
976 : /** \brief This callback gets called whenever a hang up is detected.
977 : *
978 : * When the remote connection (client or server) closes a socket
979 : * on their end, then the other end is signaled by getting this
980 : * callback called.
981 : *
982 : * Note that this callback will be called after the process_read()
983 : * and process_write() callbacks. The process_write() is unlikely
984 : * to work at all. However, the process_read() may be able to get
985 : * a few more bytes from the remove connection and act on it.
986 : *
987 : * By default a connection gets removed from the communicator
988 : * when the hang up even occurs.
989 : */
990 0 : void connection::process_hup()
991 : {
992 : // TBD: should we offer a virtual close() function to handle this
993 : // case? because the get_socket() function will not return
994 : // -1 after such errors...
995 :
996 0 : SNAP_LOG_DEBUG
997 0 : << "socket "
998 0 : << get_socket()
999 : << " of connection \""
1000 : << f_name
1001 : << "\" hang up."
1002 : << SNAP_LOG_SEND;
1003 :
1004 0 : remove_from_communicator();
1005 0 : }
1006 :
1007 :
1008 : /** \brief This callback gets called whenever an invalid socket is detected.
1009 : *
1010 : * I am not too sure at the moment when we are expected to really receive
1011 : * this call. How does a socket become invalid (i.e. does it get closed
1012 : * and then the user still attempts to use it)? In most cases, this should
1013 : * probably never happen.
1014 : *
1015 : * By default a connection gets removed from the communicator
1016 : * when the invalid even occurs.
1017 : *
1018 : * This function also logs the error.
1019 : */
1020 0 : void connection::process_invalid()
1021 : {
1022 : // TBD: should we offer a virtual close() function to handle this
1023 : // case? because the get_socket() function will not return
1024 : // -1 after such errors...
1025 :
1026 0 : SNAP_LOG_ERROR
1027 0 : << "socket of connection \""
1028 : << f_name
1029 : << "\" was marked as invalid by the kernel."
1030 : << SNAP_LOG_SEND;
1031 :
1032 0 : remove_from_communicator();
1033 0 : }
1034 :
1035 :
1036 : /** \brief Callback called whenever this connection gets added.
1037 : *
1038 : * This function gets called whenever this connection is added to
1039 : * the communicator object. This gives you the opportunity
1040 : * to do additional initialization before the run() loop gets
1041 : * called or re-entered.
1042 : */
1043 14 : void connection::connection_added()
1044 : {
1045 14 : }
1046 :
1047 :
1048 : /** \brief Callback called whenever this connection gets removed.
1049 : *
1050 : * This callback gets called after it got removed from the
1051 : * communicator object. This gives you the opportunity
1052 : * to do additional clean ups before the run() loop gets
1053 : * re-entered.
1054 : */
1055 13 : void connection::connection_removed()
1056 : {
1057 13 : }
1058 :
1059 :
1060 :
1061 6 : } // namespace ed
1062 : // vim: ts=4 sw=4 et
|
