Chuck Swiger / Pubnub_c_core2

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of Pubnub_c_core by Srdjan Veljkovic

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 */