overby.me
this repo has no description
1//===--- SwiftRemoteMirror.h - Public remote reflection interf. -*- C++ -*-===//
2//
3// This source file is part of the Swift.org open source project
4//
5// Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
6// Licensed under Apache License v2.0 with Runtime Library Exception
7//
8// See https://swift.org/LICENSE.txt for license information
9// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
10//
11//===----------------------------------------------------------------------===//
12///
13/// \file
14/// This header declares functions in the libswiftReflection library,
15/// which provides mechanisms for reflecting heap information in a
16/// remote Swift process.
17///
18//===----------------------------------------------------------------------===//
19
20#ifndef SWIFT_REFLECTION_SWIFT_REFLECTION_H
21#define SWIFT_REFLECTION_SWIFT_REFLECTION_H
22
23#include "MemoryReaderInterface.h"
24#include "SwiftRemoteMirrorTypes.h"
25
26#include <stdlib.h>
27
28/// Major version changes when there are ABI or source incompatible changes.
29#define SWIFT_REFLECTION_VERSION_MAJOR 3
30
31/// Minor version changes when new APIs are added in ABI- and source-compatible
32/// way.
33#define SWIFT_REFLECTION_VERSION_MINOR 0
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/// Get the metadata version supported by the Remote Mirror library.
40uint16_t
41swift_reflection_getSupportedMetadataVersion();
42
43/// \returns An opaque reflection context.
44SwiftReflectionContextRef
45swift_reflection_createReflectionContext(
46 void *ReaderContext,
47 PointerSizeFunction getPointerSize,
48 SizeSizeFunction getSizeSize,
49 ReadBytesFunction readBytes,
50 GetStringLengthFunction getStringLength,
51 GetSymbolAddressFunction getSymbolAddress);
52
53/// Destroys an opaque reflection context.
54void
55swift_reflection_destroyReflectionContext(SwiftReflectionContextRef Context);
56
57/// Add reflection sections for a loaded Swift image.
58void
59swift_reflection_addReflectionInfo(SwiftReflectionContextRef ContextRef,
60 swift_reflection_info_t Info);
61
62
63/// Returns a boolean indicating if the isa mask was successfully
64/// read, in which case it is stored in the isaMask out parameter.
65int
66swift_reflection_readIsaMask(SwiftReflectionContextRef ContextRef,
67 uintptr_t *outIsaMask);
68
69/// Returns an opaque type reference for a metadata pointer, or
70/// NULL if one can't be constructed.
71///
72/// This function loses information; in particular, passing the
73/// result to swift_reflection_infoForTypeRef() will not give
74/// the same result as calling swift_reflection_infoForMetadata().
75swift_typeref_t
76swift_reflection_typeRefForMetadata(SwiftReflectionContextRef ContextRef,
77 uintptr_t Metadata);
78
79/// Returns an opaque type reference for a class or closure context
80/// instance pointer, or NULL if one can't be constructed.
81///
82/// This function loses information; in particular, passing the
83/// result to swift_reflection_infoForTypeRef() will not give
84/// the same result as calling swift_reflection_infoForInstance().
85swift_typeref_t
86swift_reflection_typeRefForInstance(SwiftReflectionContextRef ContextRef,
87 uintptr_t Object);
88
89/// Returns a typeref from a mangled type name string.
90swift_typeref_t
91swift_reflection_typeRefForMangledTypeName(SwiftReflectionContextRef ContextRef,
92 const char *MangledName,
93 uint64_t Length);
94
95/// Returns a structure describing the layout of a value of a typeref.
96/// For classes, this returns the reference value itself.
97swift_typeinfo_t
98swift_reflection_infoForTypeRef(SwiftReflectionContextRef ContextRef,
99 swift_typeref_t OpaqueTypeRef);
100
101/// Returns the information about a child field of a value by index.
102swift_childinfo_t
103swift_reflection_childOfTypeRef(SwiftReflectionContextRef ContextRef,
104 swift_typeref_t OpaqueTypeRef,
105 unsigned Index);
106
107/// Returns a structure describing the layout of a class instance
108/// from the isa pointer of a class.
109swift_typeinfo_t
110swift_reflection_infoForMetadata(SwiftReflectionContextRef ContextRef,
111 uintptr_t Metadata);
112
113/// Returns the information about a child field of a class instance
114/// by index.
115swift_childinfo_t
116swift_reflection_childOfMetadata(SwiftReflectionContextRef ContextRef,
117 uintptr_t Metadata,
118 unsigned Index);
119
120/// Returns a structure describing the layout of a class or closure
121/// context instance, from a pointer to the object itself.
122swift_typeinfo_t
123swift_reflection_infoForInstance(SwiftReflectionContextRef ContextRef,
124 uintptr_t Object);
125
126/// Returns the information about a child field of a class or closure
127/// context instance.
128swift_childinfo_t
129swift_reflection_childOfInstance(SwiftReflectionContextRef ContextRef,
130 uintptr_t Object,
131 unsigned Index);
132
133/// Returns the number of generic arguments of a typeref.
134unsigned
135swift_reflection_genericArgumentCountOfTypeRef(swift_typeref_t OpaqueTypeRef);
136
137/// Returns a fully instantiated typeref for a generic argument by index.
138swift_typeref_t
139swift_reflection_genericArgumentOfTypeRef(swift_typeref_t OpaqueTypeRef,
140 unsigned Index);
141
142/// Projects the type inside of an existential container.
143///
144/// Takes the address of the start of an existential container and the typeref
145/// for the existential, and sets two out parameters:
146///
147/// - InstanceTypeRef: A type reference for the type inside of the existential
148/// container.
149/// - StartOfInstanceData: The address to the start of the inner type's instance
150/// data, which may or may not be inside the container directly.
151/// If the type is a reference type, the pointer to the instance is the first
152/// word in the container.
153///
154/// If the existential contains a value type that can fit in the first three
155/// spare words of the container, *StartOfInstanceData == InstanceAddress.
156/// If it's a value type that can't fit in three words, the data will be in
157/// its own heap box, so *StartOfInstanceData will be the address of that box.
158///
159/// Returns true if InstanceTypeRef and StartOfInstanceData contain valid
160/// valid values.
161int swift_reflection_projectExistential(SwiftReflectionContextRef ContextRef,
162 swift_addr_t ExistentialAddress,
163 swift_typeref_t ExistentialTypeRef,
164 swift_typeref_t *OutInstanceTypeRef,
165 swift_addr_t *OutStartOfInstanceData);
166
167/// Dump a brief description of the typeref as a tree to stderr.
168void swift_reflection_dumpTypeRef(swift_typeref_t OpaqueTypeRef);
169
170/// Dump information about the layout for a typeref.
171void swift_reflection_dumpInfoForTypeRef(SwiftReflectionContextRef ContextRef,
172 swift_typeref_t OpaqueTypeRef);
173
174/// Dump information about the layout of a class instance from its isa pointer.
175void swift_reflection_dumpInfoForMetadata(SwiftReflectionContextRef ContextRef,
176 uintptr_t Metadata);
177
178/// Dump information about the layout of a class or closure context instance.
179void swift_reflection_dumpInfoForInstance(SwiftReflectionContextRef ContextRef,
180 uintptr_t Object);
181
182/// Demangle a type name.
183///
184/// Copies at most `MaxLength` bytes from the demangled name string into
185/// `OutDemangledName`.
186///
187/// Returns the length of the demangled string this function tried to copy
188/// into `OutDemangledName`.
189size_t swift_reflection_demangle(const char *MangledName,
190 size_t Length,
191 char *OutDemangledName,
192 size_t MaxLength);
193
194#ifdef __cplusplus
195} // extern "C"
196#endif
197
198#endif // SWIFT_REFLECTION_SWIFT_REFLECTION_H
199