[vtk-developers] Hints for Python wrappers

[David Gobbi]

Hi All,

The MR for the VTK_EXPECTS hint is ready to merge.  To refresh your memory,
this hint adds preconditions to VTK methods so that users are less likely
to cause a segfault when they call VTK from a Python script or console:

  void SetTuple(vtkIdType tupleIdx, const double* tuple)
    VTK_EXPECTS(0 <= tupleIdx && tupleIdx < GetNumberOfTuples());

It is also used to check for null pointers.  Really, it can be check
anything to do with the state of the object or the method args, as long as
the information is available though the public API.  Failed checks cause a
ValueError exception to be raised (which is, of course, much better than a
segfault).


The next hint to be added will be VTK_SIZEHINT(), which is documented here:
http://www.vtk.org/Wiki/VTK/Wrapping_hints

After some thought, I've decided that the cleanest place to add this hint
is after the method declaration:

  double* GetPoint()
    VTK_SIZEHINT(3);

The hint takes one or two arguments.  With two arguments, the first arg is
the name of the parameter to which the hint applies.  The second argument
(the 'size') can be any C++ expression that evaluates to an integral type.
For example:

  void SetTuple(const double* tuple)
    VTK_SIZEHINT(tuple, GetNumberOfComponents());

  void InsertNextCell(vtkIdType n, vtkidType* ptIds)
    VTK_SIZEHINT(ptIds, n);

Since VTK_SIZEHINT is a variadic macro, it formally requires C++11, but
compilers have supported variadic macros for a very, very long time so I
don't expect this to be an issue.

Probably the most important use of VTK_SIZEHINT will be by people who wrap
their own VTK classes but who don't want to mess around with VTK's hints
file.


Some general info about hints:

- Any number of hints is allowed for a method. Hints are applied in the
order in which they appear.

- Hints are inherited.  If you add a hint to a base class method, then the
same hint applies to all methods that override the base class method.

Cheers,
 - David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20170830/48c6388a/attachment.html>