Srdjan Veljkovic / Pubnub_c_core

The Pubnub C-core library. It's home is on https://github.com/pubnub/c_core, this is a copy

Dependents:   Pubnub_c_core_mbed2_pal Pubnub_c_core_mbed2_pal Pubnub_c_core_mbed2_pal2

pubnub_blocking_io.h@0:d13755cfb705, 2016-11-10 (annotated)

Committer:
sveljko
Date:
Thu Nov 10 22:20:11 2016 +0000
Revision:
0:d13755cfb705
Initial commit of Pubnub C-core

Who changed what in which revision?

UserRevisionLine numberNew contents of line
sveljko 0:d13755cfb705 1 /* -*- c-file-style:"stroustrup"; indent-tabs-mode: nil -*- */
sveljko 0:d13755cfb705 2 #if !defined INC_PUBNUB_BLOCKING_IO
sveljko 0:d13755cfb705 3 #define INC_PUBNUB_BLOCKING_IO
sveljko 0:d13755cfb705 4
sveljko 0:d13755cfb705 5
sveljko 0:d13755cfb705 6 #include "pubnub_api_types.h"
sveljko 0:d13755cfb705 7
sveljko 0:d13755cfb705 8 #include <stdbool.h>
sveljko 0:d13755cfb705 9
sveljko 0:d13755cfb705 10
sveljko 0:d13755cfb705 11 /** @file pubnub_blocking_io.h
sveljko 0:d13755cfb705 12 This is the "Blocking I/O" API of the Pubnub client library.
sveljko 0:d13755cfb705 13 Functions here influence the way that Pubnub client library
sveljko 0:d13755cfb705 14 works with lower levels (the TCP/IP stack).
sveljko 0:d13755cfb705 15
sveljko 0:d13755cfb705 16 It is available on platforms that support setting blocking /
sveljko 0:d13755cfb705 17 non-blocking behavior. Be aware that, even on such platforms,
sveljko 0:d13755cfb705 18 most of these functions provide more of a hint, rather than
sveljko 0:d13755cfb705 19 a command.
sveljko 0:d13755cfb705 20 */
sveljko 0:d13755cfb705 21
sveljko 0:d13755cfb705 22
sveljko 0:d13755cfb705 23 /** Sets the usage of non-blocking I/O for a context. If non-blocking
sveljko 0:d13755cfb705 24 I/O is supported by a platform, it will be used, unless some other
sveljko 0:d13755cfb705 25 reason prevents it.
sveljko 0:d13755cfb705 26
sveljko 0:d13755cfb705 27 The exact behavior when using non-blocking I/O depends on the
sveljko 0:d13755cfb705 28 platform, but, in general:
sveljko 0:d13755cfb705 29
sveljko 0:d13755cfb705 30 - getting (or trying to get) the outcome of a Pubnub transaction
sveljko 0:d13755cfb705 31 will not block the caller's thread
sveljko 0:d13755cfb705 32
sveljko 0:d13755cfb705 33 - if outcome is gotten by polling (calling a Punbub SDK API to get
sveljko 0:d13755cfb705 34 the outcome), each poll will indicate whether the outcome is
sveljko 0:d13755cfb705 35 reached or not, so user will have to "call until the outcome is
sveljko 0:d13755cfb705 36 reached", though the user, is, of course, free to do other things
sveljko 0:d13755cfb705 37 between two "poll calls"
sveljko 0:d13755cfb705 38
sveljko 0:d13755cfb705 39 - if outcome is gotten via a callback or similar means, it is most
sveljko 0:d13755cfb705 40 likely that the actual I/O is done non-blocking anyway, but, in
sveljko 0:d13755cfb705 41 any case, user would probably see little difference between
sveljko 0:d13755cfb705 42 blocking and non-blocking I/O
sveljko 0:d13755cfb705 43
sveljko 0:d13755cfb705 44 In general, non-blocking I/O gives to more complex code, but that
sveljko 0:d13755cfb705 45 scales better.
sveljko 0:d13755cfb705 46
sveljko 0:d13755cfb705 47 @pre Call this after pubnub_init() on the context
sveljko 0:d13755cfb705 48 @param p The Context to set non-blocking I/O for
sveljko 0:d13755cfb705 49
sveljko 0:d13755cfb705 50 @return 0: OK, otherwise: error, non-blocking I/O not supported
sveljko 0:d13755cfb705 51
sveljko 0:d13755cfb705 52 */
sveljko 0:d13755cfb705 53 int pubnub_set_non_blocking_io(pubnub_t *p);
sveljko 0:d13755cfb705 54
sveljko 0:d13755cfb705 55
sveljko 0:d13755cfb705 56 /** Sets the usage of blocking I/O for a context. If blocking
sveljko 0:d13755cfb705 57 I/O is supported by a platform, it will be used, unless some other
sveljko 0:d13755cfb705 58 reason prevents it.
sveljko 0:d13755cfb705 59
sveljko 0:d13755cfb705 60 The exact behavior when using blocking I/O depends on the
sveljko 0:d13755cfb705 61 platform, but, in general:
sveljko 0:d13755cfb705 62
sveljko 0:d13755cfb705 63 - getting (or trying to get) the outcome of a Pubnub transaction
sveljko 0:d13755cfb705 64 will block the caller's thread until the outcome is actually
sveljko 0:d13755cfb705 65 reached
sveljko 0:d13755cfb705 66
sveljko 0:d13755cfb705 67 - if outcome is gotten by polling (calling a Punbub SDK API to get
sveljko 0:d13755cfb705 68 the outcome), the user will call just once and the poll will
sveljko 0:d13755cfb705 69 return when the outcome is reached (making it impossible for the
sveljko 0:d13755cfb705 70 caller to do anything on that thread until the outcome is reached)
sveljko 0:d13755cfb705 71
sveljko 0:d13755cfb705 72 - if outcome is gotten via a callback or similar means, it is most
sveljko 0:d13755cfb705 73 likely that the actual I/O is done non-blocking, but, in any case,
sveljko 0:d13755cfb705 74 user would probably see little difference between blocking and
sveljko 0:d13755cfb705 75 non-blocking I/O
sveljko 0:d13755cfb705 76
sveljko 0:d13755cfb705 77 In general, blocking I/O gives to simpler code, but that scales
sveljko 0:d13755cfb705 78 poorly.
sveljko 0:d13755cfb705 79
sveljko 0:d13755cfb705 80 @pre Call this after pubnub_init() on the context
sveljko 0:d13755cfb705 81 @param p The Context to set blocking I/O for
sveljko 0:d13755cfb705 82
sveljko 0:d13755cfb705 83 @return 0: OK, otherwise: error, blocking I/O not supported
sveljko 0:d13755cfb705 84
sveljko 0:d13755cfb705 85 */
sveljko 0:d13755cfb705 86 int pubnub_set_blocking_io(pubnub_t *p);
sveljko 0:d13755cfb705 87
sveljko 0:d13755cfb705 88
sveljko 0:d13755cfb705 89
sveljko 0:d13755cfb705 90 #endif /* defined INC_PUBNUB_BLOCKING_IO */