Robust Distributed System Nucleus (rDSN)  ver 1.0.0
service_api_c.h
1 /*
2  * The MIT License (MIT)
3  *
4  * Copyright (c) 2015 Microsoft Corporation
5  *
6  * -=- Robust Distributed System Nucleus (rDSN) -=-
7  *
8  * Permission is hereby granted, free of charge, to any person obtaining a copy
9  * of this software and associated documentation files (the "Software"), to deal
10  * in the Software without restriction, including without limitation the rights
11  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
12  * copies of the Software, and to permit persons to whom the Software is
13  * furnished to do so, subject to the following conditions:
14  *
15  * The above copyright notice and this permission notice shall be included in
16  * all copies or substantial portions of the Software.
17  *
18  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24  * THE SOFTWARE.
25  */
26 
27 /*
28  * Description:
29  * this file define the C Service API in rDSN
30  *
31  * ------------------------------------------------------------------------------
32  *
33  * The service system call API for Zion
34  * -------------------------------------------
35  * Summary:
36  * (1) rich API for common distributed system development
37  * - thread pools and tasking
38  * - thread synchronization
39  * - remote procedure calls
40  * - asynchnous file operations
41  * - envrionment inputs
42  * - rDSN app model, system and other utilities
43  * (2) portable
44  * - compilable on many platforms (currently linux, windows, FreeBSD, MacOS)
45  * - system calls are in C so that later language wrappers are possibles.
46  * (3) high performance
47  * - all low level components can be plugged with the tool API (in C++)
48  * besides the existing high performance providers;
49  * - developers can also configure thread pools, thread numbers, thread/task
50  * priorities, CPU core affinities, throttling policies etc. declaratively
51  * to build a best threading model for upper apps.
52  * (4) ease of intergration
53  * - support many languages through language wrappers based on this c interface
54  * - easy support for existing protocols (thrift/protobuf etc.)
55  * - integrate with existing platform infra with low level providers (plug-in),
56  * such as loggers, performance counters, etc.
57  * (5) rich debug, development tools and runtime policies support
58  * - tool API with task granularity semantic for further tool and runtime policy development.
59  * - rich existing tools, tracer, profiler, simulator, model checker, replayer, global checker
60  * (7) PRINCIPLE: all non-determinims must be go through these system calls so that powerful
61  * internal tools are possible - replay, model checking, replication, ...,
62  * AND, it is still OK to call other DETERMINISTIC APIs for applications.
63  *
64  * ------------------------------------------------------------------------------
65  *
66  * Revision history:
67  * Mar., 2015, @imzhenyu (Zhenyu Guo), first version in cpp
68  * July, 2015, @imzhenyu (Zhenyu Guo), refactor and refined in c
69  * Feb., 2016, @imzhenyu (Zhenyu Guo), decompose into several files for V1 release
70  * xxxx-xx-xx, author, fix bug about xxx
71  */
72 
73 # pragma once
74 
75 // common data structures and macros
76 # include <dsn/c/api_common.h>
77 
78 // rDSN uses event-driven programming model, and
79 // this file defines the task(i.e., event) abstraction and related
80 # include <dsn/c/api_task.h>
81 
82 // service API for app/framework development,
83 // including threading/tasking, thread synchronization,
84 // RPC, asynchronous file IO, environment, etc.
85 # include <dsn/c/api_layer1.h>
86 
87 // application/framework model in rDSN
88 # include <dsn/c/app_model.h>
89 
90 // while most development and operation tools
91 // in rDSN are app transparent, some are app
92 // specific, which requires developers write
93 // certain app-specific logic to enable them.
94 # include <dsn/c/app_tools.h>
95 
96 // some useful utility functions provided by rDSN,
97 // such as logging, performance counter, checksum,
98 // command line interface registration and invocation,
99 // etc.
100 # include <dsn/c/api_utilities.h>
101 
102 
103 # include <dsn/c/api_layer2.h>