[¤1] Pegasus Enhancement Proposal
(PEP)
[¤2] PEP: #340
PEP Type: Functional
[¤3] Title: The OpenPegasus Binary Protocol
[¤4] Version: 1.2
[¤5] Created: 23rd November 2008
[¤6] Authors: Michael E. Brasher
[¤7] Status: Draft
[¤8] Version History:
| [¤9] Version |
[¤10] Date |
[¤11] Author |
[¤12] Change Description |
| [¤13] 1.0 |
[¤14] 23 Nov 2008 |
[¤15] Michael E. Brasher |
[¤16] Initial submission |
| [¤17] 1.1 |
[¤18] 24 Nov 2008 |
[¤19] Michael E. Brasher |
[¤20] Minor revisions |
| [¤21] 1.2 |
[¤22] 24 Nov 2008 |
[¤23] Michael E. Brasher |
[¤24] Added on-demad binary serialization feature documentation |
[¤25]
[¤26] Abstract: This document describes the OpenPegasus binary
protocol, which allows client programs to communicate with the
OpenPegasus server over local domain and TCP sockets. This protocol
provides a faster alternative to the existing XML protocol.
[¤27] Definition of the Problem
[¤28] Currently out-of-process providers send requests to the CIM server using the standard CIM-XML protocol,
with either the CIMOMHandle or CIMClient interface. Both interfaces
employ the CIM-XML protocol, which is suboptimal. Object-level
profilers reveal that up-calls spend most of their time executing in the
CIM-XML layer. In particular, the processing of XML responses is
especially slow since responses tend to be much larger than requests.
[¤29] Proposed Solution
This document proposes a proprietary binary protocol to improve
performance between providers and the server. This protocol will
implement the same operations as the existing CIM-XML implementation.
Although this effort is aimed at improving performance between provider
and server, nothing precludes its use in ordinary client programs, both
local and remote. Like CIM-XML, the binary protocol is carried by
HTTP messages. The sections below discuss various topics of the binary
protocol.
[¤30]
[¤31] HTTP Usage
The usage of HTTP is mostly unchanged with the exception of the HTTP headers discussed in the table below.
[¤32]
[¤33]
| [¤34] HTTP Header |
[¤35] Value |
[¤36] Description |
| [¤37] Content-Type |
[¤38] application/x-openpegasus |
[¤39] This header is included in both requests and responses. It
indicates that the content (payload) of the HTTP message is encoded in
the OpenPegasus binary protocol. Any request that includes this content
type must also include the OpenPegasusServerKey HTTP header. |
| [¤40] Accept |
[¤41] application/x-openpegasus |
[¤42] This header is included in requests and indicates that the
client implementation can accept binary responses. Note that a client
may send a CIM-XML request and yet accept binary responses. |
| [¤43] OpenPegasusServerKey |
[¤44] 128 bit hexadecimal key |
[¤45] Clients cannot successfully send binary requests unless they
know the OpenPegasus server's process key. The only process that knows
this key is the provider agent (which obtains the key over an anonymous
pipe during initialization). Hence, the only process that may send
binary request is the provider agent process. Although other client
processes cannot send binary requests, they may still receive binary
responses (see the Accept header). |
[¤46]
By use of the Content-Type and Accept headers, there are four possible
request-response combinations with respect to CIM-XML and the binary
protocol. These are identified in the following table.
[¤47]
[¤48]
[¤64]
[¤65] Supported Operations
The binary protocol implements all the operations supported by the CIM-XML protocol. These are listed in the table below.
[¤66]
[¤67]
| [¤68] Operations |
| [¤69] CreationInstance |
| [¤70] GetInstance |
| [¤71] EnumerateInstances |
| [¤72] EnumerateInstanceNames |
| [¤73] ModifyInstance |
| [¤74] DeleteInstance |
| [¤75] Associators |
| [¤76] AssociatorNames |
| [¤77] References |
| [¤78] ReferenceNames |
| [¤79] CreateClass |
| [¤80] GetClass |
| [¤81] EnumerateClasses |
| [¤82] EnumerateClassNames |
| [¤83] DeleteClass |
| [¤84] ModifyClass |
| [¤85] SetQualifier |
| [¤86] GetQualifier |
| [¤87] EnumerateQualifiers |
| [¤88] DeleteQualifier |
| [¤89] ExecQuery |
| [¤90] GetProperty |
| [¤91] SetProperty |
| [¤92] InvokeMethod |
[¤93]
Each binary protocol message contains exactly the same elements as the
corresponding CIM-XML message. The elements are defined the
CIM-Operations over XML specification and so they are not repeated here.
[¤94]
[¤95] On-demand binary de-serialization
The server defers deserialization of get-instance and
enumerate-instance responses. It saves the data buffer containing the
serialization results of the provider agent. In most cases the server
can just write this data buffer back on wire to the client. This
feature improves performance by avoiding expensive desrerialization by
the server. On larger responses, this makes the server more than twice
as fast. Other operations could benefit from this optimization as well
(associators, references, etc.).
[¤96]
All error responses are encoded as CIM-XML messages whether the
expected response type is CIM-XML or binary. The binary response
decoder accepts CIM-XML responses..
[¤98]
[¤99] Provider agent trust
As mentioned above, only the provider agent process can send binary
requests to the server, although any client can receive binary
responses. Requests tend to be small compared with responses and
allowing clients to send binary requests would improve performance only
slightly but would complicate validation.
[¤100]
[¤101] Network byte order
The binary protocol adopts a "reader makes right" policy. That is the
writer (sender) of a message sends the message in the native byte order
of the process, whereas the the reader (receiver) must reorder the
request in his native byte ordering. If the writer and reader have the
same byte ordering conventions (endianess) then the expense of
reordering is avoided. The first 4 bytes of every binary message is a
magic number. The reader checks whether the byte order of the magic
number is reversed. If so, then the rest of the message is adjusted
accordingly.
[¤102]
[¤103] Data Alignment
The binary encoding aligns all basic types on 8-byte boundaries. This
ensures that basic types can be used in place without copying them into
auxiliary space. For example, a four byte integer can be
assigned directly to and from the data buffer without having to copy
the data to another memory address. We could have simply aligned basic
types on boundaries divisible by their size but this would have
required more computation while positioning the data. This protocol
clearly favors speed over size.
[¤104] Binary Message Size
Testing reveals that binary messages tend to be slightly larger than
XML messages due to 8-byte boundary alignment and 16-bit characters.
Basic types could be aligned on their natural boundries (a boundary
divisible by their size) but this would impede performance slighly.
[¤105] Arranging to use the binary protocol
When OpenPegasus is built with binary protocol support, calling CIMClient::connectLocal initiates a CIM-XML-Request/Binary-Response interaction over local domain sockets. For provider agents, this initiates a Binary-Request/Binary-Response interaction over local domain sockets. The CIMClient::connect methods initiate the conventional CIM-XML-Request/CIM-XML-Response interaction over TCP.
[¤106]
[¤107]
With the OpenPegasus SDK interfaces there is no way to initiate use of the binary protocol over TCP. However, you can use the CIMBinaryClient interface to do so. This class always establishes a CIM-XML-Request/Binary-Response interaction over TCP when using the connect methods. This class will remain experimental initially.
[¤108]
[¤109] Building binary protocol support
To build OpenPegasus with binary protocol support, set the PEGASUS_ENABLE_LOCAL_BINARY_PROTOCOL environment variable to true.
[¤110]
[¤111] Using the binary protocol over TCP
To use the binary protocol over TCP, include "Pegasus/Client/CIMClientInternal.h" and call SetBinaryResponse(true) as shown in the fragment below.
[¤112]
[¤113]
#include <Pegasus/Client/CIMClientInternal.h>
[¤114]
...
[¤115]
CIMClient client;
[¤116]
SetBinaryResponse(client, true);
[¤117]
client.connect("localhost", 5988, String(), String());
[¤118]
[¤119]
This interface is internal for now but may become a method of CIMClient later.
[¤120] Further Optimization and Improvements
The following sections address further improvement that could be made to the protocol.
[¤121]
[¤122] Extended On-demand binary de-serialization
On-demand binary de-serialization could be extended for use by other
operation types, thereby eliminating the need for deserialization of
large objects by the server. The following message types would beneit
the most form this optimization.
[¤123]
The structure already exists for GetInstance and EnumerateInstances.
Following those patterns, this optimization should be relatively easy.
[¤131] Natural boundary alignment
It may be desirable to align basic types on their natural boundaries
(divisible by their size) to reduce the size of binary messages. The
current implementation aligns basic types on 8-byte boundaries.
[¤132]
[¤133] Repeated copying between buffers
There are several places where CIMBuffers are converted to Buffers. This conversion could be eliminated if CIMBuffer were reimplemented to use Buffer. There are also many places where Buffer instances are copied. These should be the subject of further optimization.
The initial implementation is ready for review (Bugzilla bug 8171).
[¤135]
[¤136] Discussion
[¤137] Open
[¤138]
[¤139]
Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM
Corp.;
[¤140]
EMC Corporation; Symantec Corporation; The Open
Group.
[¤141]
[¤142]
Permission is hereby granted, free of charge, to any person
obtaining a copy
[¤143]
of this software and associated documentation files (the
"Software"), to
[¤144]
deal in the Software without restriction, including without
limitation the
[¤145]
rights to use, copy, modify, merge, publish, distribute,
sublicense, and/or
[¤146]
sell copies of the Software, and to permit persons to whom
the Software is
[¤147]
furnished to do so, subject to the following
conditions:
[¤148]
[¤149]
THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL
BE INCLUDED IN
[¤150]
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE
SOFTWARE IS PROVIDED
[¤151]
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT
[¤152]
LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR
[¤153]
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT
[¤154]
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN
[¤155]
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION
[¤156]
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
[¤157]