1 | #pragma once |
2 | |
3 | #include <istream> |
4 | #include <memory> |
5 | #include <string> |
6 | #include <unordered_map> |
7 | #include <vector> |
8 | |
9 | #include <ATen/core/ivalue.h> |
10 | #include <c10/core/Device.h> |
11 | #include <c10/macros/Macros.h> |
12 | #include <c10/util/Optional.h> |
13 | #include <torch/csrc/jit/mobile/module.h> |
14 | |
15 | /** |
16 | * Defines the public API for loading flatbuffer-serialized mobile modules. |
17 | * Note that this header must not include or depend on flatbuffer-defined |
18 | * types, to avoid leaking those details to PyTorch clients. |
19 | */ |
20 | |
21 | namespace torch { |
22 | namespace jit { |
23 | |
24 | /// All non-copied data pointers provided to `parse_and_initialize_*` functions |
25 | /// must be aligned to this boundary. Since the Module will point directly into |
26 | /// the data, this alignment is necessary to ensure that certain types/structs |
27 | /// are properly aligned. |
28 | constexpr size_t kFlatbufferDataAlignmentBytes = 16; |
29 | |
30 | /// Maps file names to file contents. |
31 | using = std::unordered_map<std::string, std::string>; |
32 | |
33 | // On high level, to produce a Module from a file on disk, we need to go |
34 | // through the follow steps: |
35 | // 1. Read: Read the file from disk -> memory |
36 | // 2. Deserialize: Parse the bytes to produce some in memory manipulable |
37 | // structure |
38 | // 3. Module initialization: Produce mobile::Module out of the structure |
39 | // produced in 2. |
40 | // Under this context, the structure described in 2. is the flatbuffer-defined |
41 | // type mobile::serialization::Module. However, this step/type is not visible in |
42 | // the public API. |
43 | |
44 | // Parse a mobile::Module from raw bytes. |
45 | // |
46 | // This function does steps 2+3 described above. |
47 | // |
48 | // Does not take ownership of `data`; if you want it to take ownership, see the |
49 | // shared_ptr overload of this function. |
50 | // |
51 | // If should_copy_tensor_memory is true, then the returned module will NOT have |
52 | // refences to `data`, so `data` can be freed immediately. |
53 | // |
54 | // If should_copy_tensor_memory is false, then returned module will have tensors |
55 | // that points inside of `data`; the caller will need to make sure that `data` |
56 | // outlives the returned Module. Also, `data` must be aligned to |
57 | // kFlatbufferDataAlignmentBytes. |
58 | TORCH_API mobile::Module parse_and_initialize_mobile_module( |
59 | void* data, |
60 | size_t size, // of `data`, in bytes. |
61 | c10::optional<at::Device> device = c10::nullopt, |
62 | ExtraFilesMap* = nullptr, |
63 | bool should_copy_tensor_memory = false); |
64 | |
65 | // Parse a mobile::Module from raw bytes. |
66 | // |
67 | // This function does steps 2+3 described above. |
68 | // |
69 | // The returned Module holds a reference to `data`, which must be aligned to |
70 | // kFlatbufferDataAlignmentBytes. |
71 | // |
72 | // If you do not want the Module to hold a reference to `data`, see the raw |
73 | // pointer overload of this function. |
74 | TORCH_API mobile::Module parse_and_initialize_mobile_module( |
75 | std::shared_ptr<char> data, |
76 | size_t size, // of `data`, in bytes. |
77 | c10::optional<at::Device> device = c10::nullopt, |
78 | ExtraFilesMap* = nullptr); |
79 | |
80 | // Parse a mobile::Module from raw bytes, also returning JIT-related metadata. |
81 | // |
82 | // This is the same as parse_and_initialize_mobile_module() except that it also |
83 | // extracts JIT source files and constants. Can be used to construct a |
84 | // jit::Module. |
85 | TORCH_API mobile::Module parse_and_initialize_mobile_module_for_jit( |
86 | void* data, |
87 | size_t size, // of `data`, in bytes. |
88 | ExtraFilesMap& jit_sources, |
89 | std::vector<IValue>& jit_constants, |
90 | c10::optional<at::Device> device = c10::nullopt, |
91 | ExtraFilesMap* = nullptr); |
92 | |
93 | // Load a mobile::Module from a filepath. |
94 | // |
95 | // This function does steps 1+2+3 described above. |
96 | // |
97 | // We need to have this as a convienience because Python API will need to wrap |
98 | // this. C++ clients should use one of the versions of |
99 | // parse_and_initialize_mobile_module() so they can manage the raw data more |
100 | // directly. |
101 | TORCH_API mobile::Module load_mobile_module_from_file( |
102 | const std::string& filename, |
103 | c10::optional<at::Device> device = c10::nullopt, |
104 | ExtraFilesMap* = nullptr); |
105 | |
106 | TORCH_API uint64_t get_bytecode_version(std::istream& in); |
107 | TORCH_API uint64_t get_bytecode_version(const std::string& filename); |
108 | TORCH_API uint64_t get_bytecode_version_from_bytes(char* flatbuffer_content); |
109 | |
110 | TORCH_API mobile::ModuleInfo get_module_info_from_flatbuffer( |
111 | char* flatbuffer_content); |
112 | |
113 | // The methods below are less efficient because it need to read the stream in |
114 | // its entirity to a buffer |
115 | TORCH_API mobile::Module load_mobile_module_from_stream_with_copy( |
116 | std::istream& in, |
117 | c10::optional<at::Device> device = c10::nullopt, |
118 | ExtraFilesMap* = nullptr); |
119 | |
120 | TORCH_API mobile::Module parse_flatbuffer_no_object( |
121 | std::shared_ptr<char> data, |
122 | size_t size, |
123 | c10::optional<at::Device> device); |
124 | |
125 | TORCH_API mobile::Module parse_and_initialize_mobile_module( |
126 | void* data, |
127 | size_t, |
128 | c10::optional<at::Device>, |
129 | ExtraFilesMap* , |
130 | bool should_copy_tensor_memory); |
131 | |
132 | // no op, TODO(qihan) delete |
133 | TORCH_API bool register_flatbuffer_loader(); |
134 | |
135 | } // namespace jit |
136 | } // namespace torch |
137 | |