Overview

rpc message and buffer management

all returned dsn_message_t are NOT add_ref by rDSN (unless explicitly specified), so you do not need to call msg_release_ref to release the msgs. the decision is made for easier programming, and you may consider the later dsn_rpc_xxx calls do the resource gc work for you. however, if you want to hold the message further after call dsn_rpc_xxx, you need to call dsn_msg_add_ref first before these operations, and call dsn_msg_release_ref later to ensure there is no memory leak. This is very similar to what we have above with task handles. however, this is not true for returned message from dsn_rpc_call_wait and dsn_rpc_get_response. For these two cases, developers are responsible for releasing the message handle by calling dsn_msg_release_ref. similarily, for all msgs accessable in callbacks, if you want to hold them in upper apps further beyond the callbacks, you need to call msg_add_ref, and msg_release_ref explicitly. when timeout_milliseconds == 0, [task.rpc_code%] rpc_timeout_milliseconds is used.

rpc message read/write

// apps write rpc message as follows:
       void* ptr;
       size_t size;
       dsn_msg_write_next(msg, &ptr, &size, min_size);
       write msg content to [ptr, ptr + size)
       dsn_msg_write_commit(msg, real_written_size);

// apps read rpc message as follows:
       void* ptr;
       size_t size;
       dsn_msg_read_next(msg, &ptr, &size);
       read msg content in [ptr, ptr + size)
       dsn_msg_read_commit(msg, real read size);
// if not committed, next dsn_msg_read_next returns the same read buffer

Classes
union	dsn_msg_context_t

union	dsn_global_partition_id

struct	dsn_msg_options_t

class	dsn::rpc_read_stream

class	dsn::rpc_write_stream

Macros
#define	DSN_MSGM_TIMEOUT (0x1 << 0)

#define	DSN_MSGM_HASH (0x1 << 1)

#define	DSN_MSGM_VNID (0x1 << 2)

#define	DSN_MSGM_CONTEXT (0x1 << 3)

Typedefs
typedef enum dsn_msg_serialize_format	dsn_msg_serialize_format

typedef enum dsn_msg_parameter_type_t	dsn_msg_parameter_type_t

typedef union dsn_msg_context_t	dsn_msg_context_t

typedef union dsn_global_partition_id	dsn_gpid

typedef struct dsn_msg_options_t	dsn_msg_options_t

typedef ::dsn::ref_ptr< rpc_read_stream >	dsn::rpc_read_stream_ptr

typedef ::dsn::ref_ptr< rpc_write_stream >	dsn::rpc_write_stream_ptr

Enumerations
enum	dsn_msg_serialize_format { DSF_INVALID = 0, DSF_THRIFT_BINARY = 1, DSF_THRIFT_COMPACT = 2, DSF_THRIFT_JSON = 3, DSF_PROTOC_BINARY = 4, DSF_PROTOC_JSON = 5, DSF_JSON = 6 }

enum	dsn_msg_parameter_type_t { MSG_PARAM_NONE = 0 }

Functions
DSN_API dsn_message_t	dsn_msg_create_request (dsn_task_code_t rpc_code, int timeout_milliseconds DEFAULT(0), uint64_t hash DEFAULT(0))

DSN_API dsn_message_t	dsn_msg_create_response (dsn_message_t request)

DSN_API dsn_message_t	dsn_msg_copy (dsn_message_t msg, bool clone_content, bool copy_for_receive)

DSN_API void	dsn_msg_add_ref (dsn_message_t msg)

DSN_API void	dsn_msg_release_ref (dsn_message_t msg)

DSN_API dsn_message_t	dsn_msg_create_received_request (dsn_task_code_t rpc_code, dsn_msg_serialize_format serialization_type, void *buffer, int size, uint64_t hash DEFAULT(0))

uint64_t	dsn_gpid_to_hash (dsn_gpid gpid)

void	dsn_address_size_checker ()

DSN_API void	dsn_msg_set_options (dsn_message_t msg, dsn_msg_options_t *opts, uint32_t mask)

DSN_API void	dsn_msg_get_options (dsn_message_t msg, dsn_msg_options_t *opts)

DSN_API void	dsn_msg_set_serailize_format (dsn_message_t msg, dsn_msg_serialize_format fmt)

DSN_API dsn_msg_serialize_format	dsn_msg_get_serialize_format (dsn_message_t msg)

DSN_API size_t	dsn_msg_body_size (dsn_message_t msg)

DSN_API void *	dsn_msg_rw_ptr (dsn_message_t msg, size_t offset_begin)

DSN_API dsn_address_t	dsn_msg_from_address (dsn_message_t msg)

DSN_API dsn_address_t	dsn_msg_to_address (dsn_message_t msg)

DSN_API uint64_t	dsn_msg_trace_id (dsn_message_t msg)

DSN_API dsn_task_code_t	dsn_msg_task_code (dsn_message_t msg)

DSN_API void	dsn_msg_write_next (dsn_message_t msg, void *ptr, size_t size, size_t min_size)

DSN_API void	dsn_msg_write_commit (dsn_message_t msg, size_t size)

DSN_API bool	dsn_msg_read_next (dsn_message_t msg, void *ptr, size_t size)

DSN_API void	dsn_msg_read_commit (dsn_message_t msg, size_t size)

Enumeration Type Documentation

enum dsn_msg_parameter_type_t

type of the parameter in dsn_msg_context_t

Enumerator
MSG_PARAM_NONE	nothing

Function Documentation

DSN_API dsn_message_t dsn_msg_create_request	(	dsn_task_code_t	rpc_code,
		int timeout_milliseconds	DEFAULT0,
		uint64_t hash	DEFAULT0
	)

create a rpc request message

Parameters

rpc_code	task code for this request
timeout_milliseconds	timeout for the RPC call, 0 for default value as configued in config files for the task code
hash	used for both partition and thread hash to locate which thread the request should be sent to

Returns: RPC message handle

DSN_API void dsn_msg_set_options	(	dsn_message_t	msg,
		dsn_msg_options_t *	opts,
		uint32_t	mask
	)

set options for the given message

Parameters

msg	the message handle
opts	options to be set in the message
mask	the mask composed using e.g., DSN_MSGM_TIMEOUT above to specify what to set

DSN_API void dsn_msg_get_options	(	dsn_message_t	msg,
		dsn_msg_options_t *	opts
	)

get options for the given message

Parameters

msg	the message handle
opts	options to be get

DSN_API void dsn_msg_write_next	(	dsn_message_t	msg,
		void **	ptr,
		size_t *	size,
		size_t	min_size
	)

get message write buffer

Parameters

msg	message handle
ptr	*ptr returns the writable memory pointer
size	*size returns the writable memory buffer size
min_size	*size must >= min_size

DSN_API bool dsn_msg_read_next	(	dsn_message_t	msg,
		void **	ptr,
		size_t *	size
	)

get message read buffer

Parameters

msg	message handle
ptr	*ptr points to the next read buffer
size	*size points to the size of the next buffer filled with content

Returns: true if it succeeds, false if it is already beyond the end of the message

Overview

Classes

Macros

Typedefs

Enumerations

Functions

Enumeration Type Documentation

Function Documentation