api_layer1.h

/*
 * The MIT License (MIT)
 *
 * Copyright (c) 2015 Microsoft Corporation
 * 
 * -=- Robust Distributed System Nucleus (rDSN) -=- 
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */

/*
 * Description:
 *     Service API  in rDSN
 *
 * Revision history:
 *     Mar., 2015, @imzhenyu (Zhenyu Guo), first version
 *     Feb., 2016, @imzhenyu (Zhenyu Guo), add comments for V1 release
 *     xxxx-xx-xx, author, fix bug about xxx
 */

# pragma once

# include <dsn/c/api_common.h>
# include <dsn/c/api_task.h>

# ifdef __cplusplus
extern "C" {
# endif

extern DSN_API void        dsn_task_add_ref(dsn_task_t task);

extern DSN_API void        dsn_task_release_ref(dsn_task_t task);

extern DSN_API int         dsn_task_get_ref(dsn_task_t task);

extern DSN_API bool        dsn_task_cancel(dsn_task_t task, bool wait_until_finished);

extern DSN_API void        dsn_task_set_delay(dsn_task_t task, int delay_ms);

extern DSN_API bool        dsn_task_cancel2(
    dsn_task_t task,
    bool wait_until_finished,
    /*out*/ bool* finished
    );

extern DSN_API void        dsn_task_cancel_current_timer();

extern DSN_API void        dsn_task_wait(dsn_task_t task);

extern DSN_API bool        dsn_task_wait_timeout(
    dsn_task_t task,
    int timeout_milliseconds
    );

extern DSN_API dsn_error_t dsn_task_error(dsn_task_t task);

extern DSN_API bool        dsn_task_is_running_inside(dsn_task_t t);

extern DSN_API dsn_task_tracker_t dsn_task_tracker_create(int task_bucket_count);

extern DSN_API void               dsn_task_tracker_destroy(dsn_task_tracker_t tracker);

extern DSN_API void               dsn_task_tracker_cancel_all(dsn_task_tracker_t tracker);

extern DSN_API void               dsn_task_tracker_wait_all(dsn_task_tracker_t tracker);

extern DSN_API dsn_task_t  dsn_task_create(
                            dsn_task_code_t code,
                            dsn_task_handler_t cb,
                            void* context,
                            int hash DEFAULT(0),
                            dsn_task_tracker_t tracker DEFAULT(nullptr)
                            );

extern DSN_API dsn_task_t  dsn_task_create_timer(
                            dsn_task_code_t code, 
                            dsn_task_handler_t cb, 
                            void* context, 
                            int hash,
                            int interval_milliseconds,
                            dsn_task_tracker_t tracker DEFAULT(nullptr)
                            );

extern DSN_API dsn_task_t  dsn_task_create_ex(
                            dsn_task_code_t code,               // task label
                            dsn_task_handler_t cb,              // callback function
                            dsn_task_cancelled_handler_t on_cancel, 
                            void* context,                      // context to the two callbacks above
                            int hash DEFAULT(0),                // hash to callback
                            dsn_task_tracker_t tracker DEFAULT(nullptr)
                            );

extern DSN_API dsn_task_t  dsn_task_create_timer_ex(
                            dsn_task_code_t code,
                            dsn_task_handler_t cb,
                            dsn_task_cancelled_handler_t on_cancel,
                            void* context,
                            int hash,
                            int interval_milliseconds,          // timer period
                            dsn_task_tracker_t tracker DEFAULT(nullptr)
                            );

extern DSN_API void        dsn_task_call(
                            dsn_task_t task,                                 
                            int delay_milliseconds DEFAULT(0)
                            );
typedef enum dsn_host_type_t
{
    HOST_TYPE_INVALID = 0,
    HOST_TYPE_IPV4 = 1,  
    HOST_TYPE_GROUP = 2, 
    HOST_TYPE_URI = 3,   
} dsn_host_type_t;

typedef struct dsn_address_t
{
    union u_t {
        struct {
            unsigned long long type : 2;
            unsigned long long padding : 14;
            unsigned long long port : 16;
            unsigned long long ip : 32;
        } v4;    
        struct {
            unsigned long long type : 2;
            unsigned long long uri : 62;
        } uri;   
        struct {
            unsigned long long type : 2;
            unsigned long long group : 62; 
        } group; 
        uint64_t value;
    } u;
} dsn_address_t;

extern DSN_API uint32_t      dsn_ipv4_from_host(const char* name);

extern DSN_API uint32_t      dsn_ipv4_local(const char* network_interface);

extern DSN_API dsn_address_t dsn_address_build(
                                const char* host, 
                                uint16_t port
                                );

extern DSN_API dsn_address_t dsn_address_build_ipv4(
                                uint32_t ipv4,
                                uint16_t port
                                );

extern DSN_API dsn_address_t dsn_address_build_group(
                                dsn_group_t g
                                );

extern DSN_API dsn_address_t dsn_address_build_uri(
                                dsn_uri_t uri
                                );

extern DSN_API const char*   dsn_address_to_string(dsn_address_t addr);

extern DSN_API dsn_uri_t     dsn_uri_build(const char* url);

extern DSN_API void          dsn_uri_destroy(dsn_uri_t uri);

extern DSN_API dsn_group_t   dsn_group_build(const char* name);

extern DSN_API int           dsn_group_count(dsn_group_t g);

extern DSN_API bool          dsn_group_add(dsn_group_t g, dsn_address_t ep);

extern DSN_API bool          dsn_group_remove(dsn_group_t g, dsn_address_t ep);

extern DSN_API void          dsn_group_set_leader(dsn_group_t g, dsn_address_t ep);

extern DSN_API dsn_address_t dsn_group_get_leader(dsn_group_t g);

extern DSN_API bool          dsn_group_is_leader(dsn_group_t g, dsn_address_t ep);

extern DSN_API bool          dsn_group_is_update_leader_automatically(dsn_group_t g);

extern DSN_API void          dsn_group_set_update_leader_automatically(dsn_group_t g, bool v);

extern DSN_API dsn_address_t dsn_group_next(dsn_group_t g, dsn_address_t ep);

extern DSN_API dsn_address_t dsn_group_forward_leader(dsn_group_t g);

extern DSN_API void          dsn_group_destroy(dsn_group_t g);

extern DSN_API dsn_address_t dsn_primary_address();

extern 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)
                                );

extern DSN_API dsn_message_t dsn_msg_create_response(dsn_message_t request);

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

extern DSN_API void          dsn_msg_add_ref(dsn_message_t msg);

extern DSN_API void          dsn_msg_release_ref(dsn_message_t msg);

typedef 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
} dsn_msg_serialize_format;

extern 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)
                            );

typedef enum dsn_msg_parameter_type_t
{
    MSG_PARAM_NONE = 0,           
} dsn_msg_parameter_type_t;

typedef union dsn_msg_context_t
{
    struct {
        uint64_t is_request : 1;           
        uint64_t is_forwarded : 1;         
        uint64_t unused : 4;               
        uint64_t serialize_format : 4;     
        uint64_t is_forward_supported : 1; 
        uint64_t parameter_type : 3;       
        uint64_t parameter : 50;           
    } u;
    uint64_t context;                      
} dsn_msg_context_t;

typedef union dsn_global_partition_id
{
    struct {
        int32_t app_id;          
        int32_t partition_index; 
    } u;
    uint64_t value;
} dsn_gpid;

inline uint64_t dsn_gpid_to_hash(dsn_gpid gpid)
{
    return (((uint64_t)gpid.u.app_id) << 32) + gpid.u.partition_index;
}

# define DSN_MSGM_TIMEOUT (0x1 << 0) 
# define DSN_MSGM_HASH    (0x1 << 1) 
# define DSN_MSGM_VNID    (0x1 << 2) 
# define DSN_MSGM_CONTEXT (0x1 << 3) 


typedef struct dsn_msg_options_t
{
    int               timeout_ms;  
    uint64_t          hash;        
    dsn_gpid          gpid;        
    dsn_msg_context_t context;     
} dsn_msg_options_t;

inline void dsn_address_size_checker()
{
    static_assert (sizeof(dsn_address_t) == sizeof(uint64_t),
        "sizeof(dsn_address_t) must equal to sizeof(uint64_t)");

    static_assert (sizeof(dsn_msg_context_t) == sizeof(uint64_t),
        "sizeof(dsn_msg_context_t) must equal to sizeof(uint64_t)");

    static_assert (sizeof(dsn_gpid) == sizeof(uint64_t),
        "sizeof(dsn_gpid) must equal to sizeof(uint64_t)");    
}

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

extern DSN_API void         dsn_msg_get_options(
                                dsn_message_t msg,
                                /*out*/ 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);

extern DSN_API size_t        dsn_msg_body_size(dsn_message_t msg);

extern DSN_API void*         dsn_msg_rw_ptr(dsn_message_t msg, size_t offset_begin);

extern DSN_API dsn_address_t dsn_msg_from_address(dsn_message_t msg);

extern DSN_API dsn_address_t dsn_msg_to_address(dsn_message_t msg);

extern DSN_API uint64_t      dsn_msg_trace_id(dsn_message_t msg);

extern DSN_API dsn_task_code_t dsn_msg_task_code(dsn_message_t msg);

extern DSN_API void          dsn_msg_write_next(
                                dsn_message_t msg, 
                                /*out*/ void** ptr, 
                                /*out*/ size_t* size, 
                                size_t min_size
                                );

extern DSN_API void          dsn_msg_write_commit(dsn_message_t msg, size_t size);

extern DSN_API bool          dsn_msg_read_next(
                                dsn_message_t msg, 
                                /*out*/ void** ptr, 
                                /*out*/ size_t* size
                                );

extern DSN_API void          dsn_msg_read_commit(dsn_message_t msg, size_t size);

extern DSN_API bool          dsn_rpc_register_handler(
                                dsn_task_code_t code, 
                                const char* name,
                                dsn_rpc_request_handler_t cb, 
                                void* context,
                                dsn_gpid gpid DEFAULT(dsn_gpid{ 0 })
                                );

extern DSN_API void*         dsn_rpc_unregiser_handler(
                                dsn_task_code_t code,
                                dsn_gpid gpid DEFAULT(dsn_gpid{ 0 })
                                );

extern DSN_API void          dsn_rpc_reply(dsn_message_t response, dsn_error_t err DEFAULT(0));

extern DSN_API void          dsn_rpc_forward(dsn_message_t request, dsn_address_t addr);


extern DSN_API dsn_task_t    dsn_rpc_create_response_task(
                                dsn_message_t request, 
                                dsn_rpc_response_handler_t cb, 
                                void* context, 
                                int reply_thread_hash DEFAULT(0),
                                dsn_task_tracker_t tracker DEFAULT(nullptr)
                                );

extern DSN_API dsn_task_t    dsn_rpc_create_response_task_ex(
                                dsn_message_t request, 
                                dsn_rpc_response_handler_t cb, 
                                dsn_task_cancelled_handler_t on_cancel,
                                void* context, 
                                int reply_thread_hash DEFAULT(0),
                                dsn_task_tracker_t tracker DEFAULT(nullptr)
                                );

extern DSN_API void          dsn_rpc_call(
                                dsn_address_t server,
                                dsn_task_t rpc_call
                                );

extern DSN_API dsn_message_t dsn_rpc_call_wait(
                                dsn_address_t server, 
                                dsn_message_t request
                                );

extern DSN_API void          dsn_rpc_call_one_way(
                                dsn_address_t server, 
                                dsn_message_t request
                                );

extern DSN_API dsn_message_t dsn_rpc_get_response(dsn_task_t rpc_call);

extern DSN_API void          dsn_rpc_enqueue_response(
                                dsn_task_t rpc_call, 
                                dsn_error_t err, 
                                dsn_message_t response
                                );


typedef struct
{
    void* buffer;
    int size;
} dsn_file_buffer_t;

typedef enum dsn_ctrl_code_t
{
    CTL_BATCH_INVALID = 0,
    CTL_BATCH_WRITE = 1,            
    CTL_MAX_CON_READ_OP_COUNT = 2,  
    CTL_MAX_CON_WRITE_OP_COUNT = 3, 
} dsn_ctrl_code_t;

extern DSN_API dsn_handle_t dsn_file_open(
                                const char* file_name, 
                                int flag, 
                                int pmode
                                );

extern DSN_API dsn_error_t  dsn_file_close(
                                dsn_handle_t file
                                );

extern DSN_API dsn_error_t  dsn_file_flush(
                                dsn_handle_t file
                                );

extern DSN_API void*        dsn_file_native_handle(dsn_handle_t file);

extern DSN_API dsn_task_t   dsn_file_create_aio_task(
                                dsn_task_code_t code, 
                                dsn_aio_handler_t cb, 
                                void* context,
                                int hash DEFAULT(0),
                                dsn_task_tracker_t tracker DEFAULT(nullptr)
                                );

extern DSN_API dsn_task_t   dsn_file_create_aio_task_ex(
                                dsn_task_code_t code, 
                                dsn_aio_handler_t cb, 
                                dsn_task_cancelled_handler_t on_cancel,
                                void* context,
                                int hash DEFAULT(0),
                                dsn_task_tracker_t tracker DEFAULT(nullptr)
                                );

extern DSN_API void         dsn_file_read(
                                dsn_handle_t file, 
                                char* buffer, 
                                int count, 
                                uint64_t offset, 
                                dsn_task_t cb
                                );

extern DSN_API void         dsn_file_write(
                                dsn_handle_t file, 
                                const char* buffer, 
                                int count, 
                                uint64_t offset, 
                                dsn_task_t cb
                                );

extern DSN_API void         dsn_file_write_vector(
                                dsn_handle_t file,
                                const dsn_file_buffer_t* buffers,
                                int buffer_count,
                                uint64_t offset,
                                dsn_task_t cb
                                );

extern DSN_API void         dsn_file_copy_remote_directory(
                                dsn_address_t remote, 
                                const char* source_dir, 
                                const char* dest_dir,
                                bool overwrite, 
                                dsn_task_t cb
                                );

extern DSN_API void         dsn_file_copy_remote_files(
                                dsn_address_t remote,
                                const char* source_dir, 
                                const char** source_files, 
                                const char* dest_dir, 
                                bool overwrite, 
                                dsn_task_t cb
                                );

extern DSN_API size_t       dsn_file_get_io_size(dsn_task_t cb_task);

extern DSN_API void         dsn_file_task_enqueue(
                                dsn_task_t cb_task, 
                                dsn_error_t err, 
                                size_t size
                                );


extern DSN_API uint64_t dsn_now_ns();

extern DSN_API uint64_t dsn_random64(uint64_t min, uint64_t max);

__inline uint64_t dsn_now_us() { return dsn_now_ns() / 1000; }
__inline uint64_t dsn_now_ms() { return dsn_now_ns() / 1000000; }

__inline uint32_t dsn_random32(uint32_t min, uint32_t max)
{
    return (uint32_t)(dsn_random64(min, max)); 
}

__inline double   dsn_probability()
{
    return (double)(dsn_random64(0, 1000000000)) / 1000000000.0; 
}

extern DSN_API dsn_handle_t dsn_exlock_create(bool recursive);
extern DSN_API void         dsn_exlock_destroy(dsn_handle_t l);
extern DSN_API void         dsn_exlock_lock(dsn_handle_t l);
extern DSN_API bool         dsn_exlock_try_lock(dsn_handle_t l);
extern DSN_API void         dsn_exlock_unlock(dsn_handle_t l);
extern DSN_API dsn_handle_t dsn_rwlock_nr_create();
extern DSN_API void         dsn_rwlock_nr_destroy(dsn_handle_t l);
extern DSN_API void         dsn_rwlock_nr_lock_read(dsn_handle_t l);
extern DSN_API void         dsn_rwlock_nr_unlock_read(dsn_handle_t l);
extern DSN_API bool         dsn_rwlock_nr_try_lock_read(dsn_handle_t l);
extern DSN_API void         dsn_rwlock_nr_lock_write(dsn_handle_t l);
extern DSN_API void         dsn_rwlock_nr_unlock_write(dsn_handle_t l);
extern DSN_API bool         dsn_rwlock_nr_try_lock_write(dsn_handle_t l);
extern DSN_API dsn_handle_t dsn_semaphore_create(int initial_count);
extern DSN_API void         dsn_semaphore_destroy(dsn_handle_t s);
extern DSN_API void         dsn_semaphore_signal(dsn_handle_t s, int count);
extern DSN_API void         dsn_semaphore_wait(dsn_handle_t s);
extern DSN_API bool         dsn_semaphore_wait_timeout(
    dsn_handle_t s,
    int timeout_milliseconds
    );

# ifdef __cplusplus
}
# endif