GCS  0.2.3
gcs_core.h
1 /*
2  * Copyright (C) 2008-2014 Codership Oy <info@codership.com>
3  *
4  * $Id: gcs_core.h 3455 2014-02-01 18:11:09Z alex $
5  */
6 /*
7  * This header defines generic communication layer
8  * which implements basic open/close/send/receive
9  * functions. Its purpose is to implement all
10  * functionality common to all group communication
11  * uses. Currently this amounts to action
12  * fragmentation/defragmentation and invoking backend
13  * functions.
14  * In the course of development it has become clear
15  * that such fuctionality must be collected in a
16  * separate layer.
17  * Application abstraction layer is based on this one
18  * and uses those functions for its own purposes.
19  */
20 
21 #ifndef _gcs_core_h_
22 #define _gcs_core_h_
23 
24 #include <stdint.h>
25 #include <stdlib.h>
26 
27 #include <galerautils.h>
28 
29 #include "gcs.h"
30 #include "gcs_act.h"
31 #include <gcache.h>
32 
33 /* 'static' method to register configuration variables */
34 extern void
35 gcs_core_register (gu_config_t* conf);
36 
37 struct gcs_core;
38 typedef struct gcs_core gcs_core_t;
39 
40 /*
41  * Allocates context resources private to
42  * generic communicaton layer - send/recieve buffers and the like.
43  */
44 extern gcs_core_t*
45 gcs_core_create (gu_config_t* conf,
46  gcache_t* cache,
47  const char* node_name,
48  const char* inc_addr,
49  int repl_proto_ver,
50  int appl_proto_ver);
51 
52 /* initializes action history (global seqno, group UUID). See gcs.h */
53 extern long
54 gcs_core_init (gcs_core_t* core, gcs_seqno_t seqno, const gu_uuid_t* uuid);
55 
56 /*
57  * gcs_core_open() opens connection
58  * Return values:
59  * zero - success
60  * negative - error code
61  */
62 extern long
63 gcs_core_open (gcs_core_t* conn,
64  const char* channel,
65  const char* url,
66  bool bootstrap);
67 
68 
69 /*
70  * gcs_core_close() puts connection in a closed state,
71  * cancelling all ongoing calls.
72  * Return values:
73  * zero - success
74  * negative - error code
75  */
76 extern long
77 gcs_core_close (gcs_core_t* conn);
78 
79 /*
80  * gcs_core_destroy() frees resources allocated by gcs_core_create()
81  * Return values:
82  * zero - success
83  * negative - error code
84  */
85 extern long
86 gcs_core_destroy (gcs_core_t* conn);
87 
88 /*
89  * gcs_core_send() atomically sends action to group.
90  *
91  * NOT THREAD SAFE! Access should be serialized.
92  *
93  * Return values:
94  * non-negative - amount of action bytes sent (sans headers)
95  * negative - error code
96  * -EAGAIN - operation should be retried
97  * -ENOTCONN - connection to primary component lost
98  *
99  * NOTE: Successful return code here does not guarantee delivery to group.
100  * The real status of action is determined only in gcs_core_recv() call.
101  */
102 extern ssize_t
103 gcs_core_send (gcs_core_t* core,
104  const struct gu_buf* act,
105  size_t act_size,
106  gcs_act_type_t act_type);
107 
108 /*
109  * gcs_core_recv() blocks until some action is received from group.
110  *
111  * @param repl_buf ptr to replicated action local buffer (NULL otherwise)
112  * @param timeout absolute timeout date (as in pthread_cond_timedwait())
113  *
114  * Return values:
115  * non-negative - the size of action received
116  * negative - error code
117  *
118  * @retval -ETIMEDOUT means no messages were received until timeout.
119  *
120  * NOTE: Action status (replicated or not) is carried in act_id. E.g. -ENOTCONN
121  * means connection to primary component was lost while sending,
122  * -ERESTART means that action delivery was interrupted and it must be
123  * resent.
124  */
125 extern ssize_t
126 gcs_core_recv (gcs_core_t* conn,
127  struct gcs_act_rcvd* recv_act,
128  long long timeout);
129 
130 /* Configuration functions */
131 /* Sets maximum message size to achieve requested network packet size.
132  * In case of failure returns negative error code, in case of success -
133  * resulting message payload size (size of action fragment) */
134 extern long
135 gcs_core_set_pkt_size (gcs_core_t* conn, long pkt_size);
136 
137 /* sends this node's last applied value to group */
138 extern long
139 gcs_core_set_last_applied (gcs_core_t* core, gcs_seqno_t seqno);
140 
141 /* sends status of the ended snapshot (snapshot seqno or error code) */
142 extern long
143 gcs_core_send_join (gcs_core_t* core, gcs_seqno_t seqno);
144 
145 /* sends SYNC notice, seqno currently has no meaning */
146 extern long
147 gcs_core_send_sync (gcs_core_t* core, gcs_seqno_t seqno);
148 
149 /* sends flow control message */
150 extern long
151 gcs_core_send_fc (gcs_core_t* core, const void* fc, size_t fc_size);
152 
153 extern gcs_seqno_t
154 gcs_core_caused(gcs_core_t* core);
155 
156 extern long
157 gcs_core_param_set (gcs_core_t* core, const char* key, const char* value);
158 
159 extern const char*
160 gcs_core_param_get (gcs_core_t* core, const char* key);
161 
162 #ifdef GCS_CORE_TESTING
163 
164 /* gcs_core_send() interface does not allow enough concurrency control to model
165  * various race conditions for unit testing - it is not atomic. The functions
166  * below expose gcs_core unit internals solely for the purpose of testing */
167 
168 #include "gcs_msg_type.h"
169 #include "gcs_backend.h"
170 
171 extern gcs_backend_t*
172 gcs_core_get_backend (gcs_core_t* core);
173 
174 // switches lock-step mode on/off
175 extern void
176 gcs_core_send_lock_step (gcs_core_t* core, bool enable);
177 
178 // step through action send process (send another fragment).
179 // returns positive number if there was a send thread waiting for it.
180 extern long
181 gcs_core_send_step (gcs_core_t* core, long timeout_ms);
182 
183 #endif /* GCS_CORE_TESTING */
184 
185 #endif /* _gcs_core_h_ */
Definition: gcs_act.h:19
Definition: gcs_backend.h:164
Definition: gcs_core.c:43