Line data Source code
1 : // Copyright (c) 2012-2019 Made to Order Software Corp. All Rights Reserved
2 : //
3 : // This program is free software; you can redistribute it and/or modify
4 : // it under the terms of the GNU General Public License as published by
5 : // the Free Software Foundation; either version 2 of the License, or
6 : // (at your option) any later version.
7 : //
8 : // This program is distributed in the hope that it will be useful,
9 : // but WITHOUT ANY WARRANTY; without even the implied warranty of
10 : // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 : // GNU General Public License for more details.
12 : //
13 : // You should have received a copy of the GNU General Public License
14 : // along with this program; if not, write to the Free Software
15 : // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
16 :
17 : /** \file
18 : * \brief Implementation of the connection base class.
19 : *
20 : * All the connection classes must derive from the connection base
21 : * class.
22 : *
23 : * Connections are able to handle TCP, UDP, Unix signals, etc. The
24 : * base class give us all the necessary defaults for all the connections.
25 : */
26 :
27 :
28 : // self
29 : //
30 : #include "eventdispatcher/connection.h"
31 :
32 : #include "eventdispatcher/communicator.h"
33 : #include "eventdispatcher/exception.h"
34 : #include "eventdispatcher/utils.h"
35 :
36 :
37 : // snaplogger lib
38 : //
39 : #include "snaplogger/message.h"
40 :
41 :
42 : // C lib
43 : //
44 : #include <sys/ioctl.h>
45 : #include <sys/socket.h>
46 :
47 :
48 : // last include
49 : //
50 : #include <snapdev/poison.h>
51 :
52 :
53 :
54 : namespace ed
55 : {
56 :
57 :
58 :
59 :
60 :
61 :
62 :
63 :
64 :
65 :
66 :
67 :
68 : /** \brief Initializes the connection.
69 : *
70 : * This function initializes a base connection object.
71 : */
72 0 : connection::connection()
73 : {
74 0 : }
75 :
76 :
77 : /** \brief Proceed with the cleanup of the snap_connection.
78 : *
79 : * This function cleans up a snap_connection object.
80 : */
81 0 : connection::~connection()
82 : {
83 0 : }
84 :
85 :
86 : /** \brief Remove this connection from the communicator it was added in.
87 : *
88 : * This function removes the connection from the communicator that
89 : * it was created in.
90 : *
91 : * This happens in several circumstances:
92 : *
93 : * \li When the connection is not necessary anymore
94 : * \li When the connection receives a message saying it should close
95 : * \li When the connection receives a Hang Up event
96 : * \li When the connection looks erroneous
97 : * \li When the connection looks invalid
98 : *
99 : * If the connection is not currently connected to a snap_communicator
100 : * object, then nothing happens.
101 : */
102 0 : void connection::remove_from_communicator()
103 : {
104 0 : communicator::instance()->remove_connection(shared_from_this());
105 0 : }
106 :
107 :
108 : /** \brief Retrieve the name of the connection.
109 : *
110 : * When generating an error or a log the library makes use of this name
111 : * so we actually know which type of socket generated a problem.
112 : *
113 : * \return A constant reference to the connection name.
114 : */
115 0 : std::string const & connection::get_name() const
116 : {
117 0 : return f_name;
118 : }
119 :
120 :
121 : /** \brief Change the name of the connection.
122 : *
123 : * A connection can be given a name. This is mainly for debug purposes.
124 : * We will be adding this name in errors and exceptions as they occur.
125 : *
126 : * The connection makes a copy of \p name.
127 : *
128 : * \param[in] name The name to give this connection.
129 : */
130 0 : void connection::set_name(std::string const & name)
131 : {
132 0 : f_name = name;
133 0 : }
134 :
135 :
136 : /** \brief Tell us whether this socket is a listener or not.
137 : *
138 : * By default a snap_connection object does not represent a listener
139 : * object.
140 : *
141 : * \return The base implementation returns false. Override this
142 : * virtual function if your snap_connection is a listener.
143 : */
144 0 : bool connection::is_listener() const
145 : {
146 0 : return false;
147 : }
148 :
149 :
150 : /** \brief Tell us whether this connection is listening on a Unix signal.
151 : *
152 : * By default a snap_connection object does not represent a Unix signal.
153 : * See the snap_signal implementation for further information about
154 : * Unix signal handling in this library.
155 : *
156 : * \return The base implementation returns false.
157 : */
158 0 : bool connection::is_signal() const
159 : {
160 0 : return false;
161 : }
162 :
163 :
164 : /** \brief Tell us whether this socket is used to receive data.
165 : *
166 : * If you expect to receive data on this connection, then mark it
167 : * as a reader by returning true in an overridden version of this
168 : * function.
169 : *
170 : * \return By default this function returns false (nothing to read).
171 : */
172 0 : bool connection::is_reader() const
173 : {
174 0 : return false;
175 : }
176 :
177 :
178 : /** \brief Tell us whether this socket is used to send data.
179 : *
180 : * If you expect to send data on this connection, then mark it
181 : * as a writer by returning true in an overridden version of
182 : * this function.
183 : *
184 : * \return By default this function returns false (nothing to write).
185 : */
186 0 : bool connection::is_writer() const
187 : {
188 0 : return false;
189 : }
190 :
191 :
192 : /** \brief Check whether the socket is valid for this connection.
193 : *
194 : * Some connections do not make use of a socket so just checking
195 : * whether the socket is -1 is not a good way to know whether the
196 : * socket is valid.
197 : *
198 : * The default function assumes that a socket has to be 0 or more
199 : * to be valid. Other connection implementations may overload this
200 : * function to allow other values.
201 : *
202 : * \return true if the socket is valid.
203 : */
204 0 : bool connection::valid_socket() const
205 : {
206 0 : return get_socket() >= 0;
207 : }
208 :
209 :
210 : /** \brief Check whether this connection is enabled.
211 : *
212 : * It is possible to turn a connection ON or OFF using the set_enable()
213 : * function. This function returns the current value. If true, which
214 : * is the default, the connection is considered enabled and will get
215 : * its callbacks called.
216 : *
217 : * \return true if the connection is currently enabled.
218 : */
219 0 : bool connection::is_enabled() const
220 : {
221 0 : return f_enabled;
222 : }
223 :
224 :
225 : /** \brief Change the status of a connection.
226 : *
227 : * This function let you change the status of a connection from
228 : * enabled (true) to disabled (false) and vice versa.
229 : *
230 : * A disabled connection is not listened on at all. This is similar
231 : * to returning false in all three functions is_listener(),
232 : * is_reader(), and is_writer().
233 : *
234 : * \param[in] enabled The new status of the connection.
235 : */
236 0 : void connection::set_enable(bool enabled)
237 : {
238 0 : f_enabled = enabled;
239 0 : }
240 :
241 :
242 : /** \brief Define the priority of this connection object.
243 : *
244 : * By default snap_connection objets have a priority of 100.
245 : *
246 : * You may also use the set_priority() to change the priority of a
247 : * connection at any time.
248 : *
249 : * \return The current priority of this connection.
250 : *
251 : * \sa set_priority()
252 : */
253 0 : int connection::get_priority() const
254 : {
255 0 : return f_priority;
256 : }
257 :
258 :
259 : /** \brief Change this event priority.
260 : *
261 : * This function can be used to change the default priority (which is
262 : * 100) to a larger or smaller number. A larger number makes the connection
263 : * less important and callbacks get called later. A smaller number makes
264 : * the connection more important and callbacks get called sooner.
265 : *
266 : * Note that the priority of a connection can modified at any time.
267 : * It is not guaranteed to be taken in account immediately, though.
268 : *
269 : * \exception snap_communicator_parameter_error
270 : * The priority of the event is out of range when this exception is raised.
271 : * The value must between between 0 and EVENT_MAX_PRIORITY. Any
272 : * other value raises this exception.
273 : *
274 : * \param[in] priority Priority of the event.
275 : */
276 0 : void connection::set_priority(priority_t priority)
277 : {
278 0 : if(priority < 0 || priority > EVENT_MAX_PRIORITY)
279 : {
280 : std::string err("snap_communicator::set_priority(): priority out of range,"
281 0 : " this instance of snap_communicator accepts priorities between 0 and ");
282 0 : err += std::to_string(EVENT_MAX_PRIORITY);
283 0 : err += ".";
284 0 : throw event_dispatcher_parameter_error(err);
285 : }
286 :
287 0 : f_priority = priority;
288 :
289 : // make sure that the new order is calculated when we execute
290 : // the next loop
291 : //
292 0 : communicator::instance()->set_force_sort();
293 0 : }
294 :
295 :
296 : /** \brief Less than operator to sort connections by priority.
297 : *
298 : * This function is used to know whether a connection has a higher or lower
299 : * priority. This is used when one adds, removes, or changes the priority
300 : * of a connection. The sorting itself happens in the
301 : * snap_communicator::run() which knows that something changed whenever
302 : * it checks the data.
303 : *
304 : * The result of the priority mechanism is that callbacks of items with
305 : * a smaller priorirty will be called first.
306 : *
307 : * \param[in] lhs The left hand side snap_connection.
308 : * \param[in] rhs The right hand side snap_connection.
309 : *
310 : * \return true if lhs has a smaller priority than rhs.
311 : */
312 0 : bool connection::compare(pointer_t const & lhs, pointer_t const & rhs)
313 : {
314 0 : return lhs->get_priority() < rhs->get_priority();
315 : }
316 :
317 :
318 : /** \brief Get the number of events a connection will process in a row.
319 : *
320 : * Depending on the connection, their events may get processed within
321 : * a loop. If a new event is received before the current event being
322 : * processed is done, then the system generally processes that new event
323 : * before exiting the loop.
324 : *
325 : * This count limit specifies that a certain amount of events can be
326 : * processed in a row. After that many events were processed, the loop
327 : * exits.
328 : *
329 : * Some loops may not allow for us to immediately quit that function. In
330 : * that case we go on until a breaking point is allowed.
331 : *
332 : * \return The total amount of microsecond allowed before a connection
333 : * processing returns even if additional events are already available
334 : * in connection.
335 : *
336 : * \sa snap_communicator::snap_connection::set_event_limit()
337 : */
338 0 : uint16_t connection::get_event_limit() const
339 : {
340 0 : return f_event_limit;
341 : }
342 :
343 :
344 : /** \brief Set the number of events a connection will process in a row.
345 : *
346 : * Depending on the connection, their events may get processed within
347 : * a loop. If a new event is received before the current event being
348 : * processed is done, then the system generally processes that new event
349 : * before exiting the loop.
350 : *
351 : * This count limit specifies that a certain amount of events can be
352 : * processed in a row. After that many events were processed, the loop
353 : * exits.
354 : *
355 : * Some loops may not allow for us to immediately quit that function. In
356 : * that case we go on until a breaking point is allowed.
357 : *
358 : * \param[in] event_limit Number of events to process in a row.
359 : *
360 : * \sa snap_communicator::snap_connection::get_event_limit()
361 : */
362 0 : void connection::set_event_limit(uint16_t event_limit)
363 : {
364 0 : f_event_limit = event_limit;
365 0 : }
366 :
367 :
368 : /** \brief Get the processing time limit while processing a connection events.
369 : *
370 : * Depending on the connection, their events may get processed within
371 : * a loop. If a new event is received before the current event being
372 : * processed is done, then the system generally processes that new event
373 : * before exiting the loop.
374 : *
375 : * This count limit specifies that a certain amount of events can be
376 : * processed in a row. After that many events were processed, the loop
377 : * exits.
378 : *
379 : * Some loops may not allow for us to immediately quit that function. In
380 : * that case we go on until a breaking point is allowed.
381 : *
382 : * \return The total amount of microsecond allowed before a connection
383 : * processing returns even if additional events are already available
384 : * in connection.
385 : *
386 : * \sa snap_communicator::snap_connection::set_processing_time_limit()
387 : */
388 0 : uint16_t connection::get_processing_time_limit() const
389 : {
390 0 : return f_processing_time_limit;
391 : }
392 :
393 :
394 : /** \brief Set the processing time limit while processing a connection events.
395 : *
396 : * Depending on the connection, their events may get processed within
397 : * a loop. If a new event is received before the current event being
398 : * processed is done, then the system generally processes that new event
399 : * before exiting the loop.
400 : *
401 : * This time limit gives a certain amount of time for a set of events
402 : * to get processed. The default is 0.5 seconds. Note that the system
403 : * won't stop the current event after 0.5 seconds, however, if it
404 : * takes that long or more, then it will not try to process another
405 : * event within that loop before it checks all the connections that
406 : * exist in your process.
407 : *
408 : * Some loops may not allow for us to immediately quit that function. In
409 : * that case we go on until a breaking point is allowed.
410 : *
411 : * \param[in] processing_time_limit The total amount of microsecond
412 : * allowed before a connection processing returns even if
413 : * additional events are already available in connection.
414 : *
415 : * \sa snap_communicator::snap_connection::get_processing_time_limit()
416 : */
417 0 : void connection::set_processing_time_limit(std::int32_t processing_time_limit)
418 : {
419 : // in mircoseconds.
420 : //
421 0 : f_processing_time_limit = processing_time_limit;
422 0 : }
423 :
424 :
425 : /** \brief Return the delay between ticks when this connection times out.
426 : *
427 : * All connections can include a timeout delay in microseconds which is
428 : * used to know when the wait on that specific connection times out.
429 : *
430 : * By default connections do not time out. This function returns -1
431 : * to indicate that this connection does not ever time out. To
432 : * change the timeout delay use the set_timeout_delay() function.
433 : *
434 : * \return This function returns the current timeout delay.
435 : */
436 0 : int64_t connection::get_timeout_delay() const
437 : {
438 0 : return f_timeout_delay;
439 : }
440 :
441 :
442 : /** \brief Change the timeout of this connection.
443 : *
444 : * Each connection can be setup with a timeout in microseconds.
445 : * When that delay is past, the callback function of the connection
446 : * is called with the EVENT_TIMEOUT flag set (note that the callback
447 : * may happen along other events.)
448 : *
449 : * The current date when this function gets called is the starting
450 : * point for each following trigger. Because many other callbacks
451 : * get called, it is not very likely that you will be called
452 : * exactly on time, but the ticks are guaranteed to be requested
453 : * on a non moving schedule defined as:
454 : *
455 : * \f[
456 : * \large tick_i = start-time + k \times delay
457 : * \f]
458 : *
459 : * In other words the time and date when ticks happen does not slip
460 : * with time. However, this implementation may skip one or more
461 : * ticks at any time (especially if the delay is very small).
462 : *
463 : * When a tick triggers an EVENT_TIMEOUT, the snap_communicator::run()
464 : * function calls calculate_next_tick() to calculate the time when
465 : * the next tick will occur which will always be in the function.
466 : *
467 : * \exception snap_communicator_parameter_error
468 : * This exception is raised if the timeout_us parameter is not considered
469 : * valid. The minimum value is 10 and microseconds. You may use -1 to turn
470 : * off the timeout delay feature.
471 : *
472 : * \param[in] timeout_us The new time out in microseconds.
473 : */
474 0 : void connection::set_timeout_delay(std::int64_t timeout_us)
475 : {
476 0 : if(timeout_us != -1
477 0 : && timeout_us < 10)
478 : {
479 : throw event_dispatcher_parameter_error(
480 : "snap_communicator::snap_connection::set_timeout_delay():"
481 : " timeout_us parameter cannot be less than 10"
482 : " unless it is exactly -1, "
483 0 : + std::to_string(timeout_us)
484 0 : + " is not valid.");
485 : }
486 :
487 0 : f_timeout_delay = timeout_us;
488 :
489 : // immediately calculate the next timeout date
490 : //
491 0 : f_timeout_next_date = get_current_date() + f_timeout_delay;
492 0 : }
493 :
494 :
495 : /** \brief Calculate when the next tick shall occur.
496 : *
497 : * This function calculates the date and time when the next tick
498 : * has to be triggered. This function is called after the
499 : * last time the EVENT_TIMEOUT callback was called.
500 : */
501 0 : void connection::calculate_next_tick()
502 : {
503 0 : if(f_timeout_delay == -1)
504 : {
505 : // no delay based timeout so forget about it
506 : //
507 0 : return;
508 : }
509 :
510 : // what is now?
511 : //
512 0 : int64_t const now(get_current_date());
513 :
514 : // gap between now and the last time we triggered this timeout
515 : //
516 0 : int64_t const gap(now - f_timeout_next_date);
517 0 : if(gap < 0)
518 : {
519 : // somehow we got called even though now is still larger
520 : // than f_timeout_next_date
521 : //
522 : // This message happens all the time, it is not helpful at the moment
523 : // so commenting out.
524 : //
525 : //SNAP_LOG_DEBUG
526 : // << "snap_communicator::snap_connection::calculate_next_tick()"
527 : // " called even though the next date is still larger than 'now'.";
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 0 : int64_t connection::get_timeout_date() const
555 : {
556 0 : 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 snap_communicator_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 0 : void connection::set_timeout_date(std::int64_t date_us)
578 : {
579 0 : if(date_us < -1)
580 : {
581 : throw event_dispatcher_parameter_error(
582 : "snap_communicator::snap_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 0 : f_timeout_date = date_us;
589 0 : }
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 0 : int64_t connection::get_timeout_timestamp() const
618 : {
619 0 : if(f_timeout_date != -1)
620 : {
621 : // this one is easy, it is already defined as expected
622 : //
623 0 : return f_timeout_date;
624 : }
625 :
626 0 : 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 0 : 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 0 : int64_t connection::save_timeout_timestamp()
653 : {
654 0 : f_saved_timeout_stamp = get_timeout_timestamp();
655 0 : 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 funtion 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 0 : int64_t connection::get_saved_timeout_timestamp() const
675 : {
676 0 : 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 0 : void connection::non_blocking() const
694 : {
695 0 : if(valid_socket()
696 0 : && get_socket() >= 0)
697 : {
698 0 : int optval(1);
699 0 : ioctl(get_socket(), FIONBIO, &optval);
700 : }
701 0 : }
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 : SNAP_LOG_WARNING
723 : << "snap_communicator::snap_connection::keep_alive():"
724 0 : " error "
725 0 : << e
726 0 : << " ("
727 0 : << strerror(e)
728 0 : << ") occurred trying to mark socket with SO_KEEPALIVE.";
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 0 : bool connection::is_done() const
739 : {
740 0 : 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 snap_communicator instance since we are done with
768 : * it. The default process_empty_buffer() does that for us whenver 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 0 : void connection::mark_done()
792 : {
793 0 : f_done = true;
794 :
795 : //if(!has_output())
796 : //{
797 : // process_empty_buffer();
798 : //}
799 0 : }
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 : * snap_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 snap_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 snap_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 0 : void connection::process_read()
858 : {
859 0 : }
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 0 : void connection::process_write()
877 : {
878 0 : }
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 : * snapcommunicator 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 : * snap_communicator instance if the mark_done() function was
896 : * called. Otherwise, it just ignores the message.
897 : */
898 0 : void connection::process_empty_buffer()
899 : {
900 0 : if(f_done)
901 : {
902 : SNAP_LOG_DEBUG
903 0 : << "socket "
904 0 : << get_socket()
905 0 : << " of connection \""
906 0 : << f_name
907 0 : << "\" was marked as done, removing in process_empty_buffer().";
908 :
909 0 : remove_from_communicator();
910 : }
911 0 : }
912 :
913 :
914 : /** \brief This callback gets called whenever a connection is made.
915 : *
916 : * A listening server receiving a new connection gets this function
917 : * called. The function is expected to create a new connection object
918 : * and add it to the communicator.
919 : *
920 : * \code
921 : * // get the socket from the accept() function
922 : * int const client_socket(accept());
923 : * client_impl::pointer_t connection(new client_impl(get_communicator(), client_socket));
924 : * connection->set_name("connection created by server on accept()");
925 : * get_communicator()->add_connection(connection);
926 : * \endcode
927 : */
928 0 : void connection::process_accept()
929 : {
930 0 : }
931 :
932 :
933 : /** \brief This callback gets called whenever an error is detected.
934 : *
935 : * If an error is detected on a socket, this callback function gets
936 : * called. By default the function removes the connection from
937 : * the communicator because such errors are generally non-recoverable.
938 : *
939 : * The function also logs an error message.
940 : */
941 0 : void connection::process_error()
942 : {
943 : // TBD: should we offer a virtual close() function to handle this
944 : // case? because the get_socket() function will not return
945 : // -1 after such errors...
946 :
947 0 : if(get_socket() == -1)
948 : {
949 : SNAP_LOG_DEBUG
950 0 : << "socket "
951 0 : << get_socket()
952 0 : << " of connection \""
953 0 : << f_name
954 0 : << "\" was marked as erroneous by the kernel or was closed (-1).";
955 : }
956 : else
957 : {
958 : // this happens all the time, so we changed the WARNING into a
959 : // DEBUG, too much logs by default otherwise...
960 : //
961 : SNAP_LOG_DEBUG
962 0 : << "socket "
963 0 : << get_socket()
964 0 : << " of connection \""
965 0 : << f_name
966 0 : << "\" was marked as erroneous by the kernel.";
967 : }
968 :
969 0 : remove_from_communicator();
970 0 : }
971 :
972 :
973 : /** \brief This callback gets called whenever a hang up is detected.
974 : *
975 : * When the remote connection (client or server) closes a socket
976 : * on their end, then the other end is signaled by getting this
977 : * callback called.
978 : *
979 : * Note that this callback will be called after the process_read()
980 : * and process_write() callbacks. The process_write() is unlikely
981 : * to work at all. However, the process_read() may be able to get
982 : * a few more bytes from the remove connection and act on it.
983 : *
984 : * By default a connection gets removed from the communicator
985 : * when the hang up even occurs.
986 : */
987 0 : void connection::process_hup()
988 : {
989 : // TBD: should we offer a virtual close() function to handle this
990 : // case? because the get_socket() function will not return
991 : // -1 after such errors...
992 :
993 : SNAP_LOG_DEBUG
994 0 : << "socket "
995 0 : << get_socket()
996 0 : << " of connection \""
997 0 : << f_name
998 0 : << "\" hang up.";
999 :
1000 0 : remove_from_communicator();
1001 0 : }
1002 :
1003 :
1004 : /** \brief This callback gets called whenever an invalid socket is detected.
1005 : *
1006 : * I am not too sure at the moment when we are expected to really receive
1007 : * this call. How does a socket become invalid (i.e. does it get closed
1008 : * and then the user still attempts to use it)? In most cases, this should
1009 : * probably never happen.
1010 : *
1011 : * By default a connection gets removed from the communicator
1012 : * when the invalid even occurs.
1013 : *
1014 : * This function also logs the error.
1015 : */
1016 0 : void connection::process_invalid()
1017 : {
1018 : // TBD: should we offer a virtual close() function to handle this
1019 : // case? because the get_socket() function will not return
1020 : // -1 after such errors...
1021 :
1022 : SNAP_LOG_ERROR
1023 0 : << "socket of connection \""
1024 0 : << f_name
1025 0 : << "\" was marked as invalid by the kernel.";
1026 :
1027 0 : remove_from_communicator();
1028 0 : }
1029 :
1030 :
1031 : /** \brief Callback called whenever this connection gets added.
1032 : *
1033 : * This function gets called whenever this connection is added to
1034 : * the snap_communicator object. This gives you the opportunity
1035 : * to do additional initialization before the run() loop gets
1036 : * called or re-entered.
1037 : */
1038 0 : void connection::connection_added()
1039 : {
1040 0 : }
1041 :
1042 :
1043 : /** \brief Callback called whenever this connection gets removed.
1044 : *
1045 : * This callback gets called after it got removed from the
1046 : * snap_communicator object. This gives you the opportunity
1047 : * to do additional clean ups before the run() loop gets
1048 : * re-entered.
1049 : */
1050 0 : void connection::connection_removed()
1051 : {
1052 0 : }
1053 :
1054 :
1055 :
1056 :
1057 :
1058 6 : } // namespace snap
1059 : // vim: ts=4 sw=4 et
|
