|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-EA3419BD-D757-5AC3-AE6F-DF21F794AE47" xml:lang="en"><title>Descriptor |
|
13 basics</title><shortdesc>This document describes buffer descriptors, heap descriptors, pointer |
|
14 descriptors and resizable buffer descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>Descriptors provide a safe, consistent and economical mechanism for accessing |
|
16 and manipulating strings and general binary data. </p> |
|
17 <p>A descriptor represents data which can reside in any memory location, either |
|
18 ROM or RAM. A descriptor object maintains pointer and length information to |
|
19 describe the data. All access to the data is made through the descriptor object. </p> |
|
20 <p>The area occupied by data represented by a given descriptor is considered |
|
21 to be non-expandable, even though the length of data represented can shrink |
|
22 or expand to fill that area. </p> |
|
23 <p>The set of operations which can be performed on data represented by a descriptor |
|
24 is divided into those that can modify the data and those which provide access |
|
25 but do not modify the data. This split is reflected in the structure of the |
|
26 descriptor classes. </p> |
|
27 <p>Operations on data represented by a descriptor are safe. Accidental or |
|
28 deliberate attempts to access memory outside the data area represented by |
|
29 a descriptor are caught. An illegal access is treated as bad programming rather |
|
30 than an environment or resource problem and raises an exception known as a |
|
31 panic. </p> |
|
32 <p>Descriptors make no distinction between the type of data represented; both |
|
33 strings and binary data are treated in the same way. Although some operations |
|
34 on a descriptor are intended to operate on a string, they also work on binary |
|
35 data. This unifies the handling of both strings and binary data and increases |
|
36 efficiency by allowing code to be shared. This also means that data can consist |
|
37 of a mix of string data and binary data. </p> |
|
38 <p>The concrete descriptors that programs create come in four types: </p> |
|
39 <ul> |
|
40 <li id="GUID-FFBB1AD9-1B31-5B37-8DA5-2B441385BE06"><p>Buffer descriptors - |
|
41 where the data is part of the descriptor object and the descriptor object |
|
42 lives on the program stack. </p> </li> |
|
43 <li id="GUID-2E7EF74C-0079-597F-B15A-4351D9682BA6"><p>Heap descriptors - where |
|
44 the data is part of the descriptor object and the descriptor object lives |
|
45 on the heap. </p> </li> |
|
46 <li id="GUID-DFB5D25C-FBF9-54F6-B0A4-51E58602935C"><p>Pointer descriptors |
|
47 - where the descriptor object is separate from the data it represents. </p> </li> |
|
48 <li id="GUID-AF5F3732-5E41-5E1A-AA88-C2A900C7F004"><p>Resizable buffer descriptors |
|
49 - where the descriptor is separate from the data it represents, and the data |
|
50 resides in a buffer allocated on the heap. </p> </li> |
|
51 </ul> |
|
52 <fig id="GUID-3FE00A17-DC27-5AB3-AAC8-05B4259C0834"> |
|
53 <title> Buffer descriptor </title> |
|
54 <image href="GUID-F392355C-C499-555A-85B7-1DF40492E9B2_d0e223822_href.png" placement="inline"/> |
|
55 </fig> |
|
56 <fig id="GUID-646F7A87-3D87-5856-886D-F3844D5D046C"> |
|
57 <title> Heap descriptor </title> |
|
58 <image href="GUID-084C5F8F-3310-5BDE-BB4B-110361D45AB0_d0e223830_href.png" placement="inline"/> |
|
59 </fig> |
|
60 <fig id="GUID-6A2463A0-CF76-5746-9BF3-2FC24F714A73"> |
|
61 <title> Pointer descriptor </title> |
|
62 <image href="GUID-29E54156-DF94-5B34-ACAB-1417265C950D_d0e223838_href.png" placement="inline"/> |
|
63 </fig> |
|
64 <fig id="GUID-5EE9C2A2-E654-5736-A72B-4F7A705E12DE"> |
|
65 <title> Resizable buffer descriptor </title> |
|
66 <image href="GUID-245FC4CA-EB57-5745-AD2E-79E33D43D912_d0e223846_href.png" placement="inline"/> |
|
67 </fig> |
|
68 <p>Although the four types seem to be different, the underlying class structure |
|
69 makes such differences transparent allowing them to be treated in the same |
|
70 way. </p> |
|
71 <p>Descriptor objects generally, behave as built-in types, as they can be |
|
72 safely created on the program stack and can also be safely orphaned. The heap |
|
73 descriptor is an exception to this rule. </p> |
|
74 <p>The design also avoids the memory overhead associated with virtual functions. </p> |
|
75 </conbody></concept> |