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
21namespace torch {
22namespace 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.
28constexpr size_t kFlatbufferDataAlignmentBytes = 16;
29
30/// Maps file names to file contents.
31using ExtraFilesMap = 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.
58TORCH_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* extra_files = 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.
74TORCH_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* extra_files = 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.
85TORCH_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* extra_files = 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.
101TORCH_API mobile::Module load_mobile_module_from_file(
102 const std::string& filename,
103 c10::optional<at::Device> device = c10::nullopt,
104 ExtraFilesMap* extra_files = nullptr);
105
106TORCH_API uint64_t get_bytecode_version(std::istream& in);
107TORCH_API uint64_t get_bytecode_version(const std::string& filename);
108TORCH_API uint64_t get_bytecode_version_from_bytes(char* flatbuffer_content);
109
110TORCH_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
115TORCH_API mobile::Module load_mobile_module_from_stream_with_copy(
116 std::istream& in,
117 c10::optional<at::Device> device = c10::nullopt,
118 ExtraFilesMap* extra_files = nullptr);
119
120TORCH_API mobile::Module parse_flatbuffer_no_object(
121 std::shared_ptr<char> data,
122 size_t size,
123 c10::optional<at::Device> device);
124
125TORCH_API mobile::Module parse_and_initialize_mobile_module(
126 void* data,
127 size_t,
128 c10::optional<at::Device>,
129 ExtraFilesMap* extra_files,
130 bool should_copy_tensor_memory);
131
132// no op, TODO(qihan) delete
133TORCH_API bool register_flatbuffer_loader();
134
135} // namespace jit
136} // namespace torch
137