2
.\" * Copyright (c) 2009 Red Hat, Inc.
4
.\" * All rights reserved.
6
.\" * Author: Steven Dake (sdake@redhat.com)
8
.\" * This software licensed under BSD license, the text of which follows:
10
.\" * Redistribution and use in source and binary forms, with or without
11
.\" * modification, are permitted provided that the following conditions are met:
13
.\" * - Redistributions of source code must retain the above copyright notice,
14
.\" * this list of conditions and the following disclaimer.
15
.\" * - Redistributions in binary form must reproduce the above copyright notice,
16
.\" * this list of conditions and the following disclaimer in the documentation
17
.\" * and/or other materials provided with the distribution.
18
.\" * - Neither the name of the MontaVista Software, Inc. nor the names of its
19
.\" * contributors may be used to endorse or promote products derived from this
20
.\" * software without specific prior written permission.
22
.\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
23
.\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24
.\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25
.\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
26
.\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27
.\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
28
.\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
29
.\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
30
.\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
31
.\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
32
.\" * THE POSSIBILITY OF SUCH DAMAGE.
34
.TH COROIPC_OVERVIEW 8 2009-03-21 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual"
36
The coroipcs and coroipcc libraries provide a generically reusable very high
37
performance shared memory IPC sytem for client and service applications.
38
It supports many features including:
40
65536 user services and 65536 command ids per service.
42
Shared memory implementation for very high performance.
44
A synchronous request/response channel and asynchronous response channel
47
User defined private data per IPC connection.
49
Ability to call a function per service on ipc connection and disconnection.
51
Authenticated IPC connection with ability for developer to define which
52
UIDs and GIDs are valid at connection time.
54
Fully abstracted poll system so that any poll library may be used.
56
User defined selector for determining the proper function to call per
59
.SH Description of the libraries
60
There are two shared libraries available for developing IPC client applications.
62
The first library is coroipcs.so which is responsible for the server
63
implementation. This library should be linked with the server and then
64
initialized with coroipcs_init(3).
66
Once the library is initialized, it will provide service to coroipcc.so library
69
The second library is coroipcc.so which is responsible for the client
70
implementation. This library should be linked with the client and requires
71
no initialization. This library provides communication functions for sending
72
and receiving synchronous requests, and also reading asynchronous message
73
requests from the server.
75
.SH Initializing the coroipcs library
76
To use the coroipcs library, the developer creates a coroipcs_init_state
77
structure and populates it with function names. The functions do various
78
operations described in coroipcs_init(3) man page. Not all operations must
79
be specified. If some are missing, the corosync ipcs library will
80
automatically populate the structure with internal versions which provide
83
.SH Communicating with the coroipcc clients
84
Every ipc connection is represented by a void * pointer which uniquely
85
identifies the data set for the IPC connection. Each IPC connection also
86
contains user defined private data. To obtain this private data pointer, the
87
function coroipcs_private_data_get(3) function can be called.
89
There are two channels for communication. The primary channel is the
90
synchronous request/response channel. Another channel is available for out of
91
band asynchronous responses from the server.
93
To send a response on the syncronous channel, coroipcs_response_send(3) or
94
coroipcs_response_iov_send(3) should be used. To send a message on the
95
asynchronous channel, coroipcs_dispatch_send(3) or coroipc_dispatch_iov_send(3)
98
.SH The abstracted poll system
99
There are many different poll systems in use in applications. They are usually
100
intricately tied up in the implementation of the application and each provide
101
different APIs and functionality. To manage this, the coroipcs library
102
provides callbacks in coroipcs_init(3) which should be called when a new
103
connection should be added for accept system calls or to dispatch messages.
105
These callbacks add the relevant fd to the application's poll system. When the
106
application poll system triggers the callback registered by the user defined
107
poll adding functions, they then call either coroipc_handler_accept(3) or
108
coroipc_handler_dispatch(3).
110
.SH Initializing the coroipcc library
111
No initialization is required in the coroipcc library.
113
.SH Lifecycle of an IPC connection.
114
An IPC connection is made to the server with coroipcc_service_connect(3). This
115
function connects to the server and requests channels be created for
116
communication. To disconnect, the client either exits or executes the
117
function coroipcc_service_disconnect(3).
119
.SH Synchronous communication
120
There are two functions for sending a request and receiving a response. The
121
first function coroipcc_msg_send_reply_receive(3) sends an iovector request
122
and receives a response. This function copies the response into the response
123
buffer. the second function coroipcc_msg_end_reply_receive_in_buf(3) does not
124
copy the response buffer and allows for zero-copy reading of the response
125
when the lifetime of the response buffer is known.
127
.SH Asynchronous communication
128
The coroipcc_dispatch_recv(3) function receives an out-of-band asyncronous
129
message. Unlike the synchronous communication channel, the asynchronous
130
messages are queued and can provide very high out-of-band performance.
132
To determine when to call coroipcc_dispatch_recv(3) the corosync_fd_get(3) call
133
is used to obtain a file descriptor used in the poll(2) or select(2) system
136
Finally the current dispatch flow control state can be obtained with
137
coroipcc_flow_control_get(3).
140
The ipc system is tuned for very high performance while also being comletely
141
abstracted from the underlying poll mechanism and any internalisms required
142
by the server. The ipc system achieves such high performance by using shared
143
memory as oppossed to slower techniques such as UNIX_PF sockets.
145
We intend to do further development to allow syncronous requests to return
146
messages in an asyncronous way to avoid blocking involved in the syncronous
147
request/response model used today for higher throughput in some use cases.
150
The ipc system uses default operating system security mechanics to ensure
151
ipc connections are validated. A callback used with coroipcs_init(3) is called
152
for every new ipc connection with the parameters of UID and GID. The callback
153
then determines if the UID and GID are authenticated for communication. More
154
about this topic can be viewed in the coroipcs_init(3) man page.
157
.BR coroipcs_ipc_init (3),
158
.BR coroipcs_ipc_exit (3),
159
.BR coroipcs_private_data_get (3),
160
.BR coroipcs_respone_send (3),
161
.BR coroipcs_response_iov_send (3),
162
.BR coroipcs_dispatch_send (3),
163
.BR coroipcs_dispatch_iov_send (3),
164
.BR coroipcs_refcount_inc (3),
165
.BR coroipcs_refcount_dec (3),
166
.BR coroipcs_handler_accept (3),
167
.BR coroipcs_handler_dispatch (3),
169
.BR cooripcc_service_connect (3),
170
.BR coroipcc_service_disconnect (3),
171
.BR coroipcc_msg_send_reply_receive (3),
172
.BR coroipcc_msg_send_reply_receive_in_buf (3),
173
.BR coroipcc_dispatch_recv (3),
174
.BR coroipcc_fd_get(3),
175
.BR coroipcc_dispatch_flow_control_get (3)
added
removed
man/coroipc_overview.8
