Permalink
Browse files

add comments

  • Loading branch information...
1 parent 226b831 commit adeeb43a2e5a57fff09092558aec452c7bd19156 @changchang changchang committed Mar 19, 2013
View
@@ -18,6 +18,8 @@ OBJS += src/pb-util.o
OBJS += src/pb-encode.o
OBJS += src/pb-decode.o
OBJS += src/transport.o
+OBJS += src/thread.o
+OBJS += src/protocol.o
#OBJS += jansson/*.o
OBJS := $(addprefix $(OBJDIR)/,$(OBJS))
@@ -5,6 +5,11 @@
#define MIN(X, Y) ((X) < (Y) ? (X) : (Y))
+/**
+ * uv handle close callback.
+ *
+ * @param handle closed uv handle.
+ */
void pc__handle_close_cb(uv_handle_t* handle);
#endif /* PC_COMMON_H */
@@ -3,12 +3,160 @@
#include "pomelo.h"
+/**
+ * Callback for received a handshake response from server.
+ *
+ * @param client client instance.
+ * @param data handshake response in bytes.
+ * @param len length of data.
+ * @return 0 or -1
+ */
int pc__handshake_resp(pc_client_t *client, const char *data, size_t len);
+/**
+ * Callback for received a heartbeat from server.
+ *
+ * @param client client instance.
+ * @return 0 or -1
+ */
int pc__heartbeat(pc_client_t *client);
+/**
+ * Callback for heartbeat interval event in which would send a heartbeat request
+ * to server.
+ *
+ * @param heartbeat_timer timer for heartbeat interval.
+ * @param status 0 or -1
+ */
void pc__heartbeat_cb(uv_timer_t* heartbeat_timer, int status);
+/**
+ * Callback for heartbeat timeout event.
+ *
+ * @param timeout_timer timer for heartbeat timeout.
+ * @param status 0 or -1
+ */
void pc__timeout_cb(uv_timer_t* timeout_timer, int status);
+/**
+ * Create and initiate connect request instance.
+ *
+ * @param address server address
+ * @return connect request instance
+ */
+pc_connect_t *pc_connect_req_new(struct sockaddr_in *address);
+
+/**
+ * Destroy a connect request instance and release inner resources.
+ *
+ * @param req connect request instance.
+ */
+void pc_connect_req_destroy(pc_connect_t *req);
+
+/**
+ * Connect Pomelo client to server.
+ *
+ * @param client Pomelo client instance
+ * @param req connection request
+ * @param handshake_opts handshake options send to server
+ * @param cb connection established callback
+ * @return result code, 0 for ok, -1 for error
+ */
+int pc_connect(pc_client_t *client, pc_connect_t *req,
+ json_t *handshake_opts, pc_connect_cb cb);
+
+/**
+ * Disconnect Pomelo client and reset all status back to initialted.
+ *
+ * @param client Pomelo client instance.
+ */
+void pc_disconnect(pc_client_t *client, int reset);
+
+/**
+ * Start the uv loop in client.
+ *
+ * @param client client instance.
+ * @return 0 or -1
+ */
+int pc_run(pc_client_t *client);
+
+/**
+ * Wait a condition notify of client, used internal only.
+ *
+ * @param client client instance.
+ * @param timeout wait timeout value or -1 for wait forever.
+ */
+void pc__cond_wait(pc_client_t *client, uint64_t timeout);
+
+/**
+ * Do a condition broadcast, used internal only.
+ *
+ * @param client client instance.
+ */
+void pc__cond_broadcast(pc_client_t *client);
+
+/**
+ * Callback for server connected.
+ *
+ * @param req connect request.
+ * @param status 0 or -1
+ */
+void pc__client_connected_cb(pc_connect_t* req, int status);
+
+/**
+ * Main function of worker thread.
+ *
+ * @param arg thread argument.
+ */
+void pc__worker(void *arg);
+
+/**
+ * Callback for default message parse event.
+ *
+ * @param client client instance.
+ * @param data message data in bytes.
+ * @param len length of data
+ */
+pc_msg_t *pc__default_msg_parse_cb(pc_client_t *client,
+ const char *data, size_t len);
+
+/**
+ * Callback for default message parse done event.
+ *
+ * @param client client instance.
+ * @param msg message parsed result created before.
+ */
+void pc__default_msg_parse_done_cb(pc_client_t *client, pc_msg_t *msg);
+
+/**
+ * Callback for default message encode event.
+ *
+ * @param client client instance.
+ * @param reqId request id, positive for request or 0 for notify.
+ * @param route route string.
+ * @param msg message object.
+ * @return encode result or buf.len = -1 for error.
+ */
+pc_buf_t pc__default_msg_encode_cb(pc_client_t *client, uint32_t reqId,
+ const char *route, json_t *msg);
+
+/**
+ * Callback for default message encode done event.
+ *
+ * @param client client instance.
+ * @param buf encode result created before.
+ */
+void pc__default_msg_encode_done_cb(pc_client_t * client, pc_buf_t buf);
+
+/**
+ * Callback for new package arrived event.
+ *
+ * @param type package type.
+ * @param data data of package body in bytes.
+ * @param len length of data.
+ * @param attach attach pointer.
+ */
+void pc__pkg_cb(pc_pkg_type type, const char *data, size_t len,
+ void *attach);
+
#endif /* PC_INTERNAL_H */
@@ -3,8 +3,6 @@
#include "pomelo.h"
-typedef struct pc_listener_s pc_listener_t;
-
struct pc_listener_s {
pc_event_cb cb;
ngx_queue_t queue;
@@ -13,35 +13,109 @@
typedef struct pc_map_s pc_map_t;
typedef struct pc__pair_s pc__pair_t;
+/**
+ * Map value release callback function which would be fired when the key/value
+ * pair is removing from the map.
+ *
+ * @param map pointer to the map instance.
+ * @param key the key
+ * @param value the value
+ */
typedef void (*pc_map_value_release)(pc_map_t *map, const char *key,
void *value);
+/**
+ * Map structure which used to keep key/value data.
+ */
struct pc_map_s {
+ /*! Capacity of buckets of map. */
size_t capacity;
+ /*! Array of buckets. */
ngx_queue_t *buckets;
+ /*! Value release callback function which would be invoked before the value released where the map clearing. */
pc_map_value_release release_value;
};
+/**
+ * Key/value item for map structure.
+ */
struct pc__pair_s {
const char *key;
void *value;
ngx_queue_t queue;
};
+/**
+ * Create a new map instance.
+ *
+ * @param capacity capacity of map.
+ * @param release_value value release callback for the map.
+ * @return new map instance or NULL for error.
+ */
pc_map_t *pc_map_new(size_t capacity, pc_map_value_release release_value);
-int pc_map_init(pc_map_t *map, size_t capacity, pc_map_value_release release_value);
-
+/**
+ * Destroy the map instance. Release all the key/value pair in the map and then
+ * release the instance. This function is used as couple with pc_map_new.
+ *
+ * @param map pointer to the map instance.
+ */
void pc_map_destroy(pc_map_t *map);
+/**
+ * Initiate a block allocated memory for package parser. Normally, using
+ * pc_pkg_parser_new is enough.
+ *
+ * @param map allocated memory for map instance.
+ * @param capacity capacity of map.
+ * @param release_value value release callback for the map.
+ * @return 0 for ok and -1 for error.
+ */
+int pc_map_init(pc_map_t *map, size_t capacity, pc_map_value_release release_value);
+
+/**
+ * Close a map instance and release the inner resources. But NOT release the
+ * instance itself. This function is used as couple with pc_map_init.
+ *
+ * @param map pointer of map instance.
+ */
void pc_map_close(pc_map_t *map);
+/**
+ * Add or modify a value in map. If the value with the given key already exists,
+ * the value would be replaced and the value release callback would be fired to
+ * release the value.
+ *
+ * @param map pointer to map instance.
+ * @param key key
+ * @param value value
+ * @return 0 for ok and -1 for error.
+ */
int pc_map_set(pc_map_t *map, const char *key, void *value);
+/**
+ * Get the value associated with the given key.
+ *
+ * @param map pointer to the map instance.
+ * @param key key
+ * @return the value or NULL for the value not exists.
+ */
void *pc_map_get(pc_map_t *map, const char *key);
+/**
+ * Remove a value from the map.
+ *
+ * @param map pointer of the map instance.
+ * @param key the key
+ * @return the value with the given key or NULL for the value no exists.
+ */
void *pc_map_del(pc_map_t *map, const char *key);
+/**
+ * Clear all the key/value pair in the map.
+ *
+ * @param map pointer to the map instance.
+ */
void pc_map_clear(pc_map_t *map);
-#endif
+#endif /* PC_MAP_H */
@@ -4,12 +4,41 @@
#include "uv.h"
#include "pomelo.h"
+/**
+ * Trnasport is a simple wrap layer to isolate the pc_client_t from low layer
+ * socket.
+ */
+
+/**
+ * Create a new transport instance.
+ *
+ * @param client the client instance that the new transport associated with.
+ * @return new transport instance or NULL for error.
+ */
pc_transport_t *pc_transport_new(pc_client_t *client);
+/**
+ * Disconnect the low layer socket and release the resources of transport.
+ *
+ * @param transport pointer to the transport instance.
+ */
void pc_transport_destroy(pc_transport_t *transport);
+/**
+ * Start the transport.
+ *
+ * @param transport pointer to the transport.
+ * @return 0 for ok or -1 for error.
+ */
int pc_transport_start(pc_transport_t *transport);
+/**
+ * Tcp packet arrived callback.
+ *
+ * @param socket uv_stream_t instance.
+ * @param nread bytes read.
+ * @param buf data buffer.
+ */
void pc_tp_on_tcp_read(uv_stream_t *socket, ssize_t nread, uv_buf_t buf);
#endif /* PC_TRANSPORT_H */
Oops, something went wrong.

0 comments on commit adeeb43

Please sign in to comment.