Debian Codegraph @

llvm-project/mlir/lib/Bindings/Python/IRModule.h

raw
1 //===- IRModules.h - IR Submodules of pybind module -----------------------===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8
9 #ifndef MLIR_BINDINGS_PYTHON_IRMODULES_H
10 #define MLIR_BINDINGS_PYTHON_IRMODULES_H
11
12 #include <utility>
13 #include <vector>
14 #include <optional>
15
16 #include "PybindUtils.h"
17
18 #include "mlir-c/AffineExpr.h"
19 #include "mlir-c/AffineMap.h"
20 #include "mlir-c/Diagnostics.h"
21 #include "mlir-c/IR.h"
22 #include "mlir-c/IntegerSet.h"
23 #include "llvm/ADT/DenseMap.h"
24
25 namespace mlir {
26 namespace python {
27
28 class PyBlock;
29 class PyDiagnostic;
30 class PyDiagnosticHandler;
31 class PyInsertionPoint;
32 class PyLocation;
33 class DefaultingPyLocation;
34 class PyMlirContext;
35 class DefaultingPyMlirContext;
36 class PyModule;
37 class PyOperation;
38 class PyType;
39 class PySymbolTable;
40 class PyValue;
41
42 /// Template for a reference to a concrete type which captures a python
43 /// reference to its underlying python object.
44 template <typename T>
45 class PyObjectRef {
46 public:
47 PyObjectRef(T *referrent, pybind11::object object)
48 : referrent(referrent), object(std::move(object)) {
49 assert(this->referrent &&
50 "cannot construct PyObjectRef with null referrent");
51 assert(this->object && "cannot construct PyObjectRef with null object");
52 }
53 PyObjectRef(PyObjectRef &&other)
54 : referrent(other.referrent), object(std::move(other.object)) {
55 other.referrent = nullptr;
56 assert(!other.object);
57 }
58 PyObjectRef(const PyObjectRef &other)
59 : referrent(other.referrent), object(other.object /* copies */) {}
60 ~PyObjectRef() = default;
61
62 int getRefCount() {
63 if (!object)
64 return 0;
65 return object.ref_count();
66 }
67
68 /// Releases the object held by this instance, returning it.
69 /// This is the proper thing to return from a function that wants to return
70 /// the reference. Note that this does not work from initializers.
71 pybind11::object releaseObject() {
72 assert(referrent && object);
73 referrent = nullptr;
74 auto stolen = std::move(object);
75 return stolen;
76 }
77
78 T *get() { return referrent; }
79 T *operator->() {
80 assert(referrent && object);
81 return referrent;
82 }
83 pybind11::object getObject() {
84 assert(referrent && object);
85 return object;
86 }
87 operator bool() const { return referrent && object; }
88
89 private:
90 T *referrent;
91 pybind11::object object;
92 };
93
94 /// Tracks an entry in the thread context stack. New entries are pushed onto
95 /// here for each with block that activates a new InsertionPoint, Context or
96 /// Location.
97 ///
98 /// Pushing either a Location or InsertionPoint also pushes its associated
99 /// Context. Pushing a Context will not modify the Location or InsertionPoint
100 /// unless if they are from a different context, in which case, they are
101 /// cleared.
102 class PyThreadContextEntry {
103 public:
104 enum class FrameKind {
105 Context,
106 InsertionPoint,
107 Location,
108 };
109
110 PyThreadContextEntry(FrameKind frameKind, pybind11::object context,
111 pybind11::object insertionPoint,
112 pybind11::object location)
113 : context(std::move(context)), insertionPoint(std::move(insertionPoint)),
114 location(std::move(location)), frameKind(frameKind) {}
115
116 /// Gets the top of stack context and return nullptr if not defined.
117 static PyMlirContext *getDefaultContext();
118
119 /// Gets the top of stack insertion point and return nullptr if not defined.
120 static PyInsertionPoint *getDefaultInsertionPoint();
121
122 /// Gets the top of stack location and returns nullptr if not defined.
123 static PyLocation *getDefaultLocation();
124
125 PyMlirContext *getContext();
126 PyInsertionPoint *getInsertionPoint();
127 PyLocation *getLocation();
128 FrameKind getFrameKind() { return frameKind; }
129
130 /// Stack management.
131 static PyThreadContextEntry *getTopOfStack();
132 static pybind11::object pushContext(PyMlirContext &context);
133 static void popContext(PyMlirContext &context);
134 static pybind11::object pushInsertionPoint(PyInsertionPoint &insertionPoint);
135 static void popInsertionPoint(PyInsertionPoint &insertionPoint);
136 static pybind11::object pushLocation(PyLocation &location);
137 static void popLocation(PyLocation &location);
138
139 /// Gets the thread local stack.
140 static std::vector<PyThreadContextEntry> &getStack();
141
142 private:
143 static void push(FrameKind frameKind, pybind11::object context,
144 pybind11::object insertionPoint, pybind11::object location);
145
146 /// An object reference to the PyContext.
147 pybind11::object context;
148 /// An object reference to the current insertion point.
149 pybind11::object insertionPoint;
150 /// An object reference to the current location.
151 pybind11::object location;
152 // The kind of push that was performed.
153 FrameKind frameKind;
154 };
155
156 /// Wrapper around MlirContext.
157 using PyMlirContextRef = PyObjectRef<PyMlirContext>;
158 class PyMlirContext {
159 public:
160 PyMlirContext() = delete;
161 PyMlirContext(const PyMlirContext &) = delete;
162 PyMlirContext(PyMlirContext &&) = delete;
163
164 /// For the case of a python __init__ (py::init) method, pybind11 is quite
165 /// strict about needing to return a pointer that is not yet associated to
166 /// an py::object. Since the forContext() method acts like a pool, possibly
167 /// returning a recycled context, it does not satisfy this need. The usual
168 /// way in python to accomplish such a thing is to override __new__, but
169 /// that is also not supported by pybind11. Instead, we use this entry
170 /// point which always constructs a fresh context (which cannot alias an
171 /// existing one because it is fresh).
172 static PyMlirContext *createNewContextForInit();
173
174 /// Returns a context reference for the singleton PyMlirContext wrapper for
175 /// the given context.
176 static PyMlirContextRef forContext(MlirContext context);
177 ~PyMlirContext();
178
179 /// Accesses the underlying MlirContext.
180 MlirContext get() { return context; }
181
182 /// Gets a strong reference to this context, which will ensure it is kept
183 /// alive for the life of the reference.
184 PyMlirContextRef getRef() {
185 return PyMlirContextRef(this, pybind11::cast(this));
186 }
187
188 /// Gets a capsule wrapping the void* within the MlirContext.
189 pybind11::object getCapsule();
190
191 /// Creates a PyMlirContext from the MlirContext wrapped by a capsule.
192 /// Note that PyMlirContext instances are uniqued, so the returned object
193 /// may be a pre-existing object. Ownership of the underlying MlirContext
194 /// is taken by calling this function.
195 static pybind11::object createFromCapsule(pybind11::object capsule);
196
197 /// Gets the count of live context objects. Used for testing.
198 static size_t getLiveCount();
199
200 /// Gets the count of live operations associated with this context.
201 /// Used for testing.
202 size_t getLiveOperationCount();
203
204 /// Clears the live operations map, returning the number of entries which were
205 /// invalidated. To be used as a safety mechanism so that API end-users can't
206 /// corrupt by holding references they shouldn't have accessed in the first
207 /// place.
208 size_t clearLiveOperations();
209
210 /// Gets the count of live modules associated with this context.
211 /// Used for testing.
212 size_t getLiveModuleCount();
213
214 /// Enter and exit the context manager.
215 pybind11::object contextEnter();
216 void contextExit(const pybind11::object &excType,
217 const pybind11::object &excVal,
218 const pybind11::object &excTb);
219
220 /// Attaches a Python callback as a diagnostic handler, returning a
221 /// registration object (internally a PyDiagnosticHandler).
222 pybind11::object attachDiagnosticHandler(pybind11::object callback);
223
224 private:
225 PyMlirContext(MlirContext context);
226 // Interns the mapping of live MlirContext::ptr to PyMlirContext instances,
227 // preserving the relationship that an MlirContext maps to a single
228 // PyMlirContext wrapper. This could be replaced in the future with an
229 // extension mechanism on the MlirContext for stashing user pointers.
230 // Note that this holds a handle, which does not imply ownership.
231 // Mappings will be removed when the context is destructed.
232 using LiveContextMap = llvm::DenseMap<void *, PyMlirContext *>;
233 static LiveContextMap &getLiveContexts();
234
235 // Interns all live modules associated with this context. Modules tracked
236 // in this map are valid. When a module is invalidated, it is removed
237 // from this map, and while it still exists as an instance, any
238 // attempt to access it will raise an error.
239 using LiveModuleMap =
240 llvm::DenseMap<const void *, std::pair<pybind11::handle, PyModule *>>;
241 LiveModuleMap liveModules;
242
243 // Interns all live operations associated with this context. Operations
244 // tracked in this map are valid. When an operation is invalidated, it is
245 // removed from this map, and while it still exists as an instance, any
246 // attempt to access it will raise an error.
247 using LiveOperationMap =
248 llvm::DenseMap<void *, std::pair<pybind11::handle, PyOperation *>>;
249 LiveOperationMap liveOperations;
250
251 MlirContext context;
252 friend class PyModule;
253 friend class PyOperation;
254 };
255
256 /// Used in function arguments when None should resolve to the current context
257 /// manager set instance.
258 class DefaultingPyMlirContext
259 : public Defaulting<DefaultingPyMlirContext, PyMlirContext> {
260 public:
261 using Defaulting::Defaulting;
262 static constexpr const char kTypeDescription[] = "mlir.ir.Context";
263 static PyMlirContext &resolve();
264 };
265
266 /// Base class for all objects that directly or indirectly depend on an
267 /// MlirContext. The lifetime of the context will extend at least to the
268 /// lifetime of these instances.
269 /// Immutable objects that depend on a context extend this directly.
270 class BaseContextObject {
271 public:
272 BaseContextObject(PyMlirContextRef ref) : contextRef(std::move(ref)) {
273 assert(this->contextRef &&
274 "context object constructed with null context ref");
275 }
276
277 /// Accesses the context reference.
278 PyMlirContextRef &getContext() { return contextRef; }
279
280 private:
281 PyMlirContextRef contextRef;
282 };
283
284 /// Python class mirroring the C MlirDiagnostic struct. Note that these structs
285 /// are only valid for the duration of a diagnostic callback and attempting
286 /// to access them outside of that will raise an exception. This applies to
287 /// nested diagnostics (in the notes) as well.
288 class PyDiagnostic {
289 public:
290 PyDiagnostic(MlirDiagnostic diagnostic) : diagnostic(diagnostic) {}
291 void invalidate();
292 bool isValid() { return valid; }
293 MlirDiagnosticSeverity getSeverity();
294 PyLocation getLocation();
295 pybind11::str getMessage();
296 pybind11::tuple getNotes();
297
298 private:
299 MlirDiagnostic diagnostic;
300
301 void checkValid();
302 /// If notes have been materialized from the diagnostic, then this will
303 /// be populated with the corresponding objects (all castable to
304 /// PyDiagnostic).
305 std::optional<pybind11::tuple> materializedNotes;
306 bool valid = true;
307 };
308
309 /// Represents a diagnostic handler attached to the context. The handler's
310 /// callback will be invoked with PyDiagnostic instances until the detach()
311 /// method is called or the context is destroyed. A diagnostic handler can be
312 /// the subject of a `with` block, which will detach it when the block exits.
313 ///
314 /// Since diagnostic handlers can call back into Python code which can do
315 /// unsafe things (i.e. recursively emitting diagnostics, raising exceptions,
316 /// etc), this is generally not deemed to be a great user-level API. Users
317 /// should generally use some form of DiagnosticCollector. If the handler raises
318 /// any exceptions, they will just be emitted to stderr and dropped.
319 ///
320 /// The unique usage of this class means that its lifetime management is
321 /// different from most other parts of the API. Instances are always created
322 /// in an attached state and can transition to a detached state by either:
323 /// a) The context being destroyed and unregistering all handlers.
324 /// b) An explicit call to detach().
325 /// The object may remain live from a Python perspective for an arbitrary time
326 /// after detachment, but there is nothing the user can do with it (since there
327 /// is no way to attach an existing handler object).
328 class PyDiagnosticHandler {
329 public:
330 PyDiagnosticHandler(MlirContext context, pybind11::object callback);
331 ~PyDiagnosticHandler();
332
333 bool isAttached() { return registeredID.has_value(); }
334 bool getHadError() { return hadError; }
335
336 /// Detaches the handler. Does nothing if not attached.
337 void detach();
338
339 pybind11::object contextEnter() { return pybind11::cast(this); }
340 void contextExit(const pybind11::object &excType,
341 const pybind11::object &excVal,
342 const pybind11::object &excTb) {
343 detach();
344 }
345
346 private:
347 MlirContext context;
348 pybind11::object callback;
349 std::optional<MlirDiagnosticHandlerID> registeredID;
350 bool hadError = false;
351 friend class PyMlirContext;
352 };
353
354 /// Wrapper around an MlirDialect. This is exported as `DialectDescriptor` in
355 /// order to differentiate it from the `Dialect` base class which is extended by
356 /// plugins which extend dialect functionality through extension python code.
357 /// This should be seen as the "low-level" object and `Dialect` as the
358 /// high-level, user facing object.
359 class PyDialectDescriptor : public BaseContextObject {
360 public:
361 PyDialectDescriptor(PyMlirContextRef contextRef, MlirDialect dialect)
362 : BaseContextObject(std::move(contextRef)), dialect(dialect) {}
363
364 MlirDialect get() { return dialect; }
365
366 private:
367 MlirDialect dialect;
368 };
369
370 /// User-level object for accessing dialects with dotted syntax such as:
371 /// ctx.dialect.std
372 class PyDialects : public BaseContextObject {
373 public:
374 PyDialects(PyMlirContextRef contextRef)
375 : BaseContextObject(std::move(contextRef)) {}
376
377 MlirDialect getDialectForKey(const std::string &key, bool attrError);
378 };
379
380 /// User-level dialect object. For dialects that have a registered extension,
381 /// this will be the base class of the extension dialect type. For un-extended,
382 /// objects of this type will be returned directly.
383 class PyDialect {
384 public:
385 PyDialect(pybind11::object descriptor) : descriptor(std::move(descriptor)) {}
386
387 pybind11::object getDescriptor() { return descriptor; }
388
389 private:
390 pybind11::object descriptor;
391 };
392
393 /// Wrapper around an MlirDialectRegistry.
394 /// Upon construction, the Python wrapper takes ownership of the
395 /// underlying MlirDialectRegistry.
396 class PyDialectRegistry {
397 public:
398 PyDialectRegistry() : registry(mlirDialectRegistryCreate()) {}
399 PyDialectRegistry(MlirDialectRegistry registry) : registry(registry) {}
400 ~PyDialectRegistry() {
401 if (!mlirDialectRegistryIsNull(registry))
402 mlirDialectRegistryDestroy(registry);
403 }
404 PyDialectRegistry(PyDialectRegistry &) = delete;
405 PyDialectRegistry(PyDialectRegistry &&other) : registry(other.registry) {
406 other.registry = {nullptr};
407 }
408
409 operator MlirDialectRegistry() const { return registry; }
410 MlirDialectRegistry get() const { return registry; }
411
412 pybind11::object getCapsule();
413 static PyDialectRegistry createFromCapsule(pybind11::object capsule);
414
415 private:
416 MlirDialectRegistry registry;
417 };
418
419 /// Wrapper around an MlirLocation.
420 class PyLocation : public BaseContextObject {
421 public:
422 PyLocation(PyMlirContextRef contextRef, MlirLocation loc)
423 : BaseContextObject(std::move(contextRef)), loc(loc) {}
424
425 operator MlirLocation() const { return loc; }
426 MlirLocation get() const { return loc; }
427
428 /// Enter and exit the context manager.
429 pybind11::object contextEnter();
430 void contextExit(const pybind11::object &excType,
431 const pybind11::object &excVal,
432 const pybind11::object &excTb);
433
434 /// Gets a capsule wrapping the void* within the MlirLocation.
435 pybind11::object getCapsule();
436
437 /// Creates a PyLocation from the MlirLocation wrapped by a capsule.
438 /// Note that PyLocation instances are uniqued, so the returned object
439 /// may be a pre-existing object. Ownership of the underlying MlirLocation
440 /// is taken by calling this function.
441 static PyLocation createFromCapsule(pybind11::object capsule);
442
443 private:
444 MlirLocation loc;
445 };
446
447 /// Used in function arguments when None should resolve to the current context
448 /// manager set instance.
449 class DefaultingPyLocation
450 : public Defaulting<DefaultingPyLocation, PyLocation> {
451 public:
452 using Defaulting::Defaulting;
453 static constexpr const char kTypeDescription[] = "mlir.ir.Location";
454 static PyLocation &resolve();
455
456 operator MlirLocation() const { return *get(); }
457 };
458
459 /// Wrapper around MlirModule.
460 /// This is the top-level, user-owned object that contains regions/ops/blocks.
461 class PyModule;
462 using PyModuleRef = PyObjectRef<PyModule>;
463 class PyModule : public BaseContextObject {
464 public:
465 /// Returns a PyModule reference for the given MlirModule. This may return
466 /// a pre-existing or new object.
467 static PyModuleRef forModule(MlirModule module);
468 PyModule(PyModule &) = delete;
469 PyModule(PyMlirContext &&) = delete;
470 ~PyModule();
471
472 /// Gets the backing MlirModule.
473 MlirModule get() { return module; }
474
475 /// Gets a strong reference to this module.
476 PyModuleRef getRef() {
477 return PyModuleRef(this,
478 pybind11::reinterpret_borrow<pybind11::object>(handle));
479 }
480
481 /// Gets a capsule wrapping the void* within the MlirModule.
482 /// Note that the module does not (yet) provide a corresponding factory for
483 /// constructing from a capsule as that would require uniquing PyModule
484 /// instances, which is not currently done.
485 pybind11::object getCapsule();
486
487 /// Creates a PyModule from the MlirModule wrapped by a capsule.
488 /// Note that PyModule instances are uniqued, so the returned object
489 /// may be a pre-existing object. Ownership of the underlying MlirModule
490 /// is taken by calling this function.
491 static pybind11::object createFromCapsule(pybind11::object capsule);
492
493 private:
494 PyModule(PyMlirContextRef contextRef, MlirModule module);
495 MlirModule module;
496 pybind11::handle handle;
497 };
498
499 /// Base class for PyOperation and PyOpView which exposes the primary, user
500 /// visible methods for manipulating it.
501 class PyOperationBase {
502 public:
503 virtual ~PyOperationBase() = default;
504 /// Implements the bound 'print' method and helps with others.
505 void print(pybind11::object fileObject, bool binary,
506 std::optional<int64_t> largeElementsLimit, bool enableDebugInfo,
507 bool prettyDebugInfo, bool printGenericOpForm, bool useLocalScope,
508 bool assumeVerified);
509 pybind11::object getAsm(bool binary,
510 std::optional<int64_t> largeElementsLimit,
511 bool enableDebugInfo, bool prettyDebugInfo,
512 bool printGenericOpForm, bool useLocalScope,
513 bool assumeVerified);
514
515 // Implement the bound 'writeBytecode' method.
516 void writeBytecode(const pybind11::object &fileObject);
517
518 /// Moves the operation before or after the other operation.
519 void moveAfter(PyOperationBase &other);
520 void moveBefore(PyOperationBase &other);
521
522 /// Each must provide access to the raw Operation.
523 virtual PyOperation &getOperation() = 0;
524 };
525
526 /// Wrapper around PyOperation.
527 /// Operations exist in either an attached (dependent) or detached (top-level)
528 /// state. In the detached state (as on creation), an operation is owned by
529 /// the creator and its lifetime extends either until its reference count
530 /// drops to zero or it is attached to a parent, at which point its lifetime
531 /// is bounded by its top-level parent reference.
532 class PyOperation;
533 using PyOperationRef = PyObjectRef<PyOperation>;
534 class PyOperation : public PyOperationBase, public BaseContextObject {
535 public:
536 ~PyOperation() override;
537 PyOperation &getOperation() override { return *this; }
538
539 /// Returns a PyOperation for the given MlirOperation, optionally associating
540 /// it with a parentKeepAlive.
541 static PyOperationRef
542 forOperation(PyMlirContextRef contextRef, MlirOperation operation,
543 pybind11::object parentKeepAlive = pybind11::object());
544
545 /// Creates a detached operation. The operation must not be associated with
546 /// any existing live operation.
547 static PyOperationRef
548 createDetached(PyMlirContextRef contextRef, MlirOperation operation,
549 pybind11::object parentKeepAlive = pybind11::object());
550
551 /// Detaches the operation from its parent block and updates its state
552 /// accordingly.
553 void detachFromParent() {
554 mlirOperationRemoveFromParent(getOperation());
555 setDetached();
556 parentKeepAlive = pybind11::object();
557 }
558
559 /// Gets the backing operation.
560 operator MlirOperation() const { return get(); }
561 MlirOperation get() const {
562 checkValid();
563 return operation;
564 }
565
566 PyOperationRef getRef() {
567 return PyOperationRef(
568 this, pybind11::reinterpret_borrow<pybind11::object>(handle));
569 }
570
571 bool isAttached() { return attached; }
572 void setAttached(const pybind11::object &parent = pybind11::object()) {
573 assert(!attached && "operation already attached");
574 attached = true;
575 }
576 void setDetached() {
577 assert(attached && "operation already detached");
578 attached = false;
579 }
580 void checkValid() const;
581
582 /// Gets the owning block or raises an exception if the operation has no
583 /// owning block.
584 PyBlock getBlock();
585
586 /// Gets the parent operation or raises an exception if the operation has
587 /// no parent.
588 std::optional<PyOperationRef> getParentOperation();
589
590 /// Gets a capsule wrapping the void* within the MlirOperation.
591 pybind11::object getCapsule();
592
593 /// Creates a PyOperation from the MlirOperation wrapped by a capsule.
594 /// Ownership of the underlying MlirOperation is taken by calling this
595 /// function.
596 static pybind11::object createFromCapsule(pybind11::object capsule);
597
598 /// Creates an operation. See corresponding python docstring.
599 static pybind11::object
600 create(const std::string &name, std::optional<std::vector<PyType *>> results,
601 std::optional<std::vector<PyValue *>> operands,
602 std::optional<pybind11::dict> attributes,
603 std::optional<std::vector<PyBlock *>> successors, int regions,
604 DefaultingPyLocation location, const pybind11::object &ip);
605
606 /// Creates an OpView suitable for this operation.
607 pybind11::object createOpView();
608
609 /// Erases the underlying MlirOperation, removes its pointer from the
610 /// parent context's live operations map, and sets the valid bit false.
611 void erase();
612
613 /// Invalidate the operation.
614 void setInvalid() { valid = false; }
615
616 /// Clones this operation.
617 pybind11::object clone(const pybind11::object &ip);
618
619 private:
620 PyOperation(PyMlirContextRef contextRef, MlirOperation operation);
621 static PyOperationRef createInstance(PyMlirContextRef contextRef,
622 MlirOperation operation,
623 pybind11::object parentKeepAlive);
624
625 MlirOperation operation;
626 pybind11::handle handle;
627 // Keeps the parent alive, regardless of whether it is an Operation or
628 // Module.
629 // TODO: As implemented, this facility is only sufficient for modeling the
630 // trivial module parent back-reference. Generalize this to also account for
631 // transitions from detached to attached and address TODOs in the
632 // ir_operation.py regarding testing corresponding lifetime guarantees.
633 pybind11::object parentKeepAlive;
634 bool attached = true;
635 bool valid = true;
636
637 friend class PyOperationBase;
638 friend class PySymbolTable;
639 };
640
641 /// A PyOpView is equivalent to the C++ "Op" wrappers: these are the basis for
642 /// providing more instance-specific accessors and serve as the base class for
643 /// custom ODS-style operation classes. Since this class is subclass on the
644 /// python side, it must present an __init__ method that operates in pure
645 /// python types.
646 class PyOpView : public PyOperationBase {
647 public:
648 PyOpView(const pybind11::object &operationObject);
649 PyOperation &getOperation() override { return operation; }
650
651 static pybind11::object createRawSubclass(const pybind11::object &userClass);
652
653 pybind11::object getOperationObject() { return operationObject; }
654
655 static pybind11::object
656 buildGeneric(const pybind11::object &cls, pybind11::list resultTypeList,
657 pybind11::list operandList,
658 std::optional<pybind11::dict> attributes,
659 std::optional<std::vector<PyBlock *>> successors,
660 std::optional<int> regions, DefaultingPyLocation location,
661 const pybind11::object &maybeIp);
662
663 private:
664 PyOperation &operation; // For efficient, cast-free access from C++
665 pybind11::object operationObject; // Holds the reference.
666 };
667
668 /// Wrapper around an MlirRegion.
669 /// Regions are managed completely by their containing operation. Unlike the
670 /// C++ API, the python API does not support detached regions.
671 class PyRegion {
672 public:
673 PyRegion(PyOperationRef parentOperation, MlirRegion region)
674 : parentOperation(std::move(parentOperation)), region(region) {
675 assert(!mlirRegionIsNull(region) && "python region cannot be null");
676 }
677 operator MlirRegion() const { return region; }
678
679 MlirRegion get() { return region; }
680 PyOperationRef &getParentOperation() { return parentOperation; }
681
682 void checkValid() { return parentOperation->checkValid(); }
683
684 private:
685 PyOperationRef parentOperation;
686 MlirRegion region;
687 };
688
689 /// Wrapper around an MlirBlock.
690 /// Blocks are managed completely by their containing operation. Unlike the
691 /// C++ API, the python API does not support detached blocks.
692 class PyBlock {
693 public:
694 PyBlock(PyOperationRef parentOperation, MlirBlock block)
695 : parentOperation(std::move(parentOperation)), block(block) {
696 assert(!mlirBlockIsNull(block) && "python block cannot be null");
697 }
698
699 MlirBlock get() { return block; }
700 PyOperationRef &getParentOperation() { return parentOperation; }
701
702 void checkValid() { return parentOperation->checkValid(); }
703
704 private:
705 PyOperationRef parentOperation;
706 MlirBlock block;
707 };
708
709 /// An insertion point maintains a pointer to a Block and a reference operation.
710 /// Calls to insert() will insert a new operation before the
711 /// reference operation. If the reference operation is null, then appends to
712 /// the end of the block.
713 class PyInsertionPoint {
714 public:
715 /// Creates an insertion point positioned after the last operation in the
716 /// block, but still inside the block.
717 PyInsertionPoint(PyBlock &block);
718 /// Creates an insertion point positioned before a reference operation.
719 PyInsertionPoint(PyOperationBase &beforeOperationBase);
720
721 /// Shortcut to create an insertion point at the beginning of the block.
722 static PyInsertionPoint atBlockBegin(PyBlock &block);
723 /// Shortcut to create an insertion point before the block terminator.
724 static PyInsertionPoint atBlockTerminator(PyBlock &block);
725
726 /// Inserts an operation.
727 void insert(PyOperationBase &operationBase);
728
729 /// Enter and exit the context manager.
730 pybind11::object contextEnter();
731 void contextExit(const pybind11::object &excType,
732 const pybind11::object &excVal,
733 const pybind11::object &excTb);
734
735 PyBlock &getBlock() { return block; }
736
737 private:
738 // Trampoline constructor that avoids null initializing members while
739 // looking up parents.
740 PyInsertionPoint(PyBlock block, std::optional<PyOperationRef> refOperation)
741 : refOperation(std::move(refOperation)), block(std::move(block)) {}
742
743 std::optional<PyOperationRef> refOperation;
744 PyBlock block;
745 };
746 /// Wrapper around the generic MlirType.
747 /// The lifetime of a type is bound by the PyContext that created it.
748 class PyType : public BaseContextObject {
749 public:
750 PyType(PyMlirContextRef contextRef, MlirType type)
751 : BaseContextObject(std::move(contextRef)), type(type) {}
752 bool operator==(const PyType &other);
753 operator MlirType() const { return type; }
754 MlirType get() const { return type; }
755
756 /// Gets a capsule wrapping the void* within the MlirType.
757 pybind11::object getCapsule();
758
759 /// Creates a PyType from the MlirType wrapped by a capsule.
760 /// Note that PyType instances are uniqued, so the returned object
761 /// may be a pre-existing object. Ownership of the underlying MlirType
762 /// is taken by calling this function.
763 static PyType createFromCapsule(pybind11::object capsule);
764
765 private:
766 MlirType type;
767 };
768
769 /// CRTP base classes for Python types that subclass Type and should be
770 /// castable from it (i.e. via something like IntegerType(t)).
771 /// By default, type class hierarchies are one level deep (i.e. a
772 /// concrete type class extends PyType); however, intermediate python-visible
773 /// base classes can be modeled by specifying a BaseTy.
774 template <typename DerivedTy, typename BaseTy = PyType>
775 class PyConcreteType : public BaseTy {
776 public:
777 // Derived classes must define statics for:
778 // IsAFunctionTy isaFunction
779 // const char *pyClassName
780 using ClassTy = pybind11::class_<DerivedTy, BaseTy>;
781 using IsAFunctionTy = bool (*)(MlirType);
782
783 PyConcreteType() = default;
784 PyConcreteType(PyMlirContextRef contextRef, MlirType t)
785 : BaseTy(std::move(contextRef), t) {}
786 PyConcreteType(PyType &orig)
787 : PyConcreteType(orig.getContext(), castFrom(orig)) {}
788
789 static MlirType castFrom(PyType &orig) {
790 if (!DerivedTy::isaFunction(orig)) {
791 auto origRepr = pybind11::repr(pybind11::cast(orig)).cast<std::string>();
792 throw SetPyError(PyExc_ValueError, llvm::Twine("Cannot cast type to ") +
793 DerivedTy::pyClassName +
794 " (from " + origRepr + ")");
795 }
796 return orig;
797 }
798
799 static void bind(pybind11::module &m) {
800 auto cls = ClassTy(m, DerivedTy::pyClassName, pybind11::module_local());
801 cls.def(pybind11::init<PyType &>(), pybind11::keep_alive<0, 1>(),
802 pybind11::arg("cast_from_type"));
803 cls.def_static(
804 "isinstance",
805 [](PyType &otherType) -> bool {
806 return DerivedTy::isaFunction(otherType);
807 },
808 pybind11::arg("other"));
809 DerivedTy::bindDerived(cls);
810 }
811
812 /// Implemented by derived classes to add methods to the Python subclass.
813 static void bindDerived(ClassTy &m) {}
814 };
815
816 /// Wrapper around the generic MlirAttribute.
817 /// The lifetime of a type is bound by the PyContext that created it.
818 class PyAttribute : public BaseContextObject {
819 public:
820 PyAttribute(PyMlirContextRef contextRef, MlirAttribute attr)
821 : BaseContextObject(std::move(contextRef)), attr(attr) {}
822 bool operator==(const PyAttribute &other);
823 operator MlirAttribute() const { return attr; }
824 MlirAttribute get() const { return attr; }
825
826 /// Gets a capsule wrapping the void* within the MlirAttribute.
827 pybind11::object getCapsule();
828
829 /// Creates a PyAttribute from the MlirAttribute wrapped by a capsule.
830 /// Note that PyAttribute instances are uniqued, so the returned object
831 /// may be a pre-existing object. Ownership of the underlying MlirAttribute
832 /// is taken by calling this function.
833 static PyAttribute createFromCapsule(pybind11::object capsule);
834
835 private:
836 MlirAttribute attr;
837 };
838
839 /// Represents a Python MlirNamedAttr, carrying an optional owned name.
840 /// TODO: Refactor this and the C-API to be based on an Identifier owned
841 /// by the context so as to avoid ownership issues here.
842 class PyNamedAttribute {
843 public:
844 /// Constructs a PyNamedAttr that retains an owned name. This should be
845 /// used in any code that originates an MlirNamedAttribute from a python
846 /// string.
847 /// The lifetime of the PyNamedAttr must extend to the lifetime of the
848 /// passed attribute.
849 PyNamedAttribute(MlirAttribute attr, std::string ownedName);
850
851 MlirNamedAttribute namedAttr;
852
853 private:
854 // Since the MlirNamedAttr contains an internal pointer to the actual
855 // memory of the owned string, it must be heap allocated to remain valid.
856 // Otherwise, strings that fit within the small object optimization threshold
857 // will have their memory address change as the containing object is moved,
858 // resulting in an invalid aliased pointer.
859 std::unique_ptr<std::string> ownedName;
860 };
861
862 /// CRTP base classes for Python attributes that subclass Attribute and should
863 /// be castable from it (i.e. via something like StringAttr(attr)).
864 /// By default, attribute class hierarchies are one level deep (i.e. a
865 /// concrete attribute class extends PyAttribute); however, intermediate
866 /// python-visible base classes can be modeled by specifying a BaseTy.
867 template <typename DerivedTy, typename BaseTy = PyAttribute>
868 class PyConcreteAttribute : public BaseTy {
869 public:
870 // Derived classes must define statics for:
871 // IsAFunctionTy isaFunction
872 // const char *pyClassName
873 using ClassTy = pybind11::class_<DerivedTy, BaseTy>;
874 using IsAFunctionTy = bool (*)(MlirAttribute);
875
876 PyConcreteAttribute() = default;
877 PyConcreteAttribute(PyMlirContextRef contextRef, MlirAttribute attr)
878 : BaseTy(std::move(contextRef), attr) {}
879 PyConcreteAttribute(PyAttribute &orig)
880 : PyConcreteAttribute(orig.getContext(), castFrom(orig)) {}
881
882 static MlirAttribute castFrom(PyAttribute &orig) {
883 if (!DerivedTy::isaFunction(orig)) {
884 auto origRepr = pybind11::repr(pybind11::cast(orig)).cast<std::string>();
885 throw SetPyError(PyExc_ValueError,
886 llvm::Twine("Cannot cast attribute to ") +
887 DerivedTy::pyClassName + " (from " + origRepr + ")");
888 }
889 return orig;
890 }
891
892 static void bind(pybind11::module &m) {
893 auto cls = ClassTy(m, DerivedTy::pyClassName, pybind11::buffer_protocol(),
894 pybind11::module_local());
895 cls.def(pybind11::init<PyAttribute &>(), pybind11::keep_alive<0, 1>(),
896 pybind11::arg("cast_from_attr"));
897 cls.def_static(
898 "isinstance",
899 [](PyAttribute &otherAttr) -> bool {
900 return DerivedTy::isaFunction(otherAttr);
901 },
902 pybind11::arg("other"));
903 cls.def_property_readonly("type", [](PyAttribute &attr) {
904 return PyType(attr.getContext(), mlirAttributeGetType(attr));
905 });
906 DerivedTy::bindDerived(cls);
907 }
908
909 /// Implemented by derived classes to add methods to the Python subclass.
910 static void bindDerived(ClassTy &m) {}
911 };
912
913 /// Wrapper around the generic MlirValue.
914 /// Values are managed completely by the operation that resulted in their
915 /// definition. For op result value, this is the operation that defines the
916 /// value. For block argument values, this is the operation that contains the
917 /// block to which the value is an argument (blocks cannot be detached in Python
918 /// bindings so such operation always exists).
919 class PyValue {
920 public:
921 PyValue(PyOperationRef parentOperation, MlirValue value)
922 : parentOperation(std::move(parentOperation)), value(value) {}
923 operator MlirValue() const { return value; }
924
925 MlirValue get() { return value; }
926 PyOperationRef &getParentOperation() { return parentOperation; }
927
928 void checkValid() { return parentOperation->checkValid(); }
929
930 /// Gets a capsule wrapping the void* within the MlirValue.
931 pybind11::object getCapsule();
932
933 /// Creates a PyValue from the MlirValue wrapped by a capsule. Ownership of
934 /// the underlying MlirValue is still tied to the owning operation.
935 static PyValue createFromCapsule(pybind11::object capsule);
936
937 private:
938 PyOperationRef parentOperation;
939 MlirValue value;
940 };
941
942 /// Wrapper around MlirAffineExpr. Affine expressions are owned by the context.
943 class PyAffineExpr : public BaseContextObject {
944 public:
945 PyAffineExpr(PyMlirContextRef contextRef, MlirAffineExpr affineExpr)
946 : BaseContextObject(std::move(contextRef)), affineExpr(affineExpr) {}
947 bool operator==(const PyAffineExpr &other);
948 operator MlirAffineExpr() const { return affineExpr; }
949 MlirAffineExpr get() const { return affineExpr; }
950
951 /// Gets a capsule wrapping the void* within the MlirAffineExpr.
952 pybind11::object getCapsule();
953
954 /// Creates a PyAffineExpr from the MlirAffineExpr wrapped by a capsule.
955 /// Note that PyAffineExpr instances are uniqued, so the returned object
956 /// may be a pre-existing object. Ownership of the underlying MlirAffineExpr
957 /// is taken by calling this function.
958 static PyAffineExpr createFromCapsule(pybind11::object capsule);
959
960 PyAffineExpr add(const PyAffineExpr &other) const;
961 PyAffineExpr mul(const PyAffineExpr &other) const;
962 PyAffineExpr floorDiv(const PyAffineExpr &other) const;
963 PyAffineExpr ceilDiv(const PyAffineExpr &other) const;
964 PyAffineExpr mod(const PyAffineExpr &other) const;
965
966 private:
967 MlirAffineExpr affineExpr;
968 };
969
970 class PyAffineMap : public BaseContextObject {
971 public:
972 PyAffineMap(PyMlirContextRef contextRef, MlirAffineMap affineMap)
973 : BaseContextObject(std::move(contextRef)), affineMap(affineMap) {}
974 bool operator==(const PyAffineMap &other);
975 operator MlirAffineMap() const { return affineMap; }
976 MlirAffineMap get() const { return affineMap; }
977
978 /// Gets a capsule wrapping the void* within the MlirAffineMap.
979 pybind11::object getCapsule();
980
981 /// Creates a PyAffineMap from the MlirAffineMap wrapped by a capsule.
982 /// Note that PyAffineMap instances are uniqued, so the returned object
983 /// may be a pre-existing object. Ownership of the underlying MlirAffineMap
984 /// is taken by calling this function.
985 static PyAffineMap createFromCapsule(pybind11::object capsule);
986
987 private:
988 MlirAffineMap affineMap;
989 };
990
991 class PyIntegerSet : public BaseContextObject {
992 public:
993 PyIntegerSet(PyMlirContextRef contextRef, MlirIntegerSet integerSet)
994 : BaseContextObject(std::move(contextRef)), integerSet(integerSet) {}
995 bool operator==(const PyIntegerSet &other);
996 operator MlirIntegerSet() const { return integerSet; }
997 MlirIntegerSet get() const { return integerSet; }
998
999 /// Gets a capsule wrapping the void* within the MlirIntegerSet.
1000 pybind11::object getCapsule();
1001
1002 /// Creates a PyIntegerSet from the MlirAffineMap wrapped by a capsule.
1003 /// Note that PyIntegerSet instances may be uniqued, so the returned object
1004 /// may be a pre-existing object. Integer sets are owned by the context.
1005 static PyIntegerSet createFromCapsule(pybind11::object capsule);
1006
1007 private:
1008 MlirIntegerSet integerSet;
1009 };
1010
1011 /// Bindings for MLIR symbol tables.
1012 class PySymbolTable {
1013 public:
1014 /// Constructs a symbol table for the given operation.
1015 explicit PySymbolTable(PyOperationBase &operation);
1016
1017 /// Destroys the symbol table.
1018 ~PySymbolTable() { mlirSymbolTableDestroy(symbolTable); }
1019
1020 /// Returns the symbol (opview) with the given name, throws if there is no
1021 /// such symbol in the table.
1022 pybind11::object dunderGetItem(const std::string &name);
1023
1024 /// Removes the given operation from the symbol table and erases it.
1025 void erase(PyOperationBase &symbol);
1026
1027 /// Removes the operation with the given name from the symbol table and erases
1028 /// it, throws if there is no such symbol in the table.
1029 void dunderDel(const std::string &name);
1030
1031 /// Inserts the given operation into the symbol table. The operation must have
1032 /// the symbol trait.
1033 PyAttribute insert(PyOperationBase &symbol);
1034
1035 /// Gets and sets the name of a symbol op.
1036 static PyAttribute getSymbolName(PyOperationBase &symbol);
1037 static void setSymbolName(PyOperationBase &symbol, const std::string &name);
1038
1039 /// Gets and sets the visibility of a symbol op.
1040 static PyAttribute getVisibility(PyOperationBase &symbol);
1041 static void setVisibility(PyOperationBase &symbol,
1042 const std::string &visibility);
1043
1044 /// Replaces all symbol uses within an operation. See the API
1045 /// mlirSymbolTableReplaceAllSymbolUses for all caveats.
1046 static void replaceAllSymbolUses(const std::string &oldSymbol,
1047 const std::string &newSymbol,
1048 PyOperationBase &from);
1049
1050 /// Walks all symbol tables under and including 'from'.
1051 static void walkSymbolTables(PyOperationBase &from, bool allSymUsesVisible,
1052 pybind11::object callback);
1053
1054 /// Casts the bindings class into the C API structure.
1055 operator MlirSymbolTable() { return symbolTable; }
1056
1057 private:
1058 PyOperationRef operation;
1059 MlirSymbolTable symbolTable;
1060 };
1061
1062 void populateIRAffine(pybind11::module &m);
1063 void populateIRAttributes(pybind11::module &m);
1064 void populateIRCore(pybind11::module &m);
1065 void populateIRInterfaces(pybind11::module &m);
1066 void populateIRTypes(pybind11::module &m);
1067
1068 } // namespace python
1069 } // namespace mlir
1070
1071 namespace pybind11 {
1072 namespace detail {
1073
1074 template <>
1075 struct type_caster<mlir::python::DefaultingPyMlirContext>
1076 : MlirDefaultingCaster<mlir::python::DefaultingPyMlirContext> {};
1077 template <>
1078 struct type_caster<mlir::python::DefaultingPyLocation>
1079 : MlirDefaultingCaster<mlir::python::DefaultingPyLocation> {};
1080
1081 } // namespace detail
1082 } // namespace pybind11
1083
1084 #endif // MLIR_BINDINGS_PYTHON_IRMODULES_H