You Want Me To Recurse WHAT‽

Some packaging tips for unmirrored dpkg repos

Fri, 23 Jul 2021 00:00:00 -0500

Debian package has one wart I’ve been trying to fight with:

The entire package mechanism assumes your source code is a managed mirror of upstream.

For those of us who don’t want to mirror upstream and apply debian packaging rebases and patches, there’s a way to pull from upstream (especially github branch/tag archives) and produce a self-contained and self-cleaning build.

I’ll use LAStools as my example since this is what I just finished packaging:

#!/usr/bin/make -f

include /usr/share/dpkg/default.mk

SOURCE_NAME:=$(DEB_SOURCE)-$(DEB_VERSION_EPOCH_UPSTREAM)
SOURCE_TAR:=$(SOURCE_NAME).tar.gz
REMOTE_TAR:=https://github.com/LAStools/LAStools/archive/master.tar.gz
SOURCE_DIR:=LAStools-master/

clean:
        rm -rf $(SOURCE_DIR) $(SOURCE_TAR) obj-$(DEB_HOST_MULTIARCH)
        dh clean

build:
        wget -O $(SOURCE_TAR) $(REMOTE_TAR)
        tar -xaf $(SOURCE_TAR)
        for i in $$(cat debian/patches/series); do patch -p1 < debian/patches/$$i; done
        dh build --buildsystem=cmake --sourcedir=$(SOURCE_DIR)

%:
        dh $@  --sourcedir=$(SOURCE_DIR)


override_dh_auto_configure:
        dh_auto_configure --    -DCMAKE_LIBRARY_PATH=$(DEB_HOST_MULTIARCH) -DBUILD_SHARED_LIBS=ON

This rules file will download the master.tar.gz archive from github, extract it to produce a ./LAStools-master, patch with the necessary cmake and security patches in debian/patches (similar to using quilt), then build in the LAStools-master subdirectory using cmake.

If you’re using multiarch (you should be), you can use dh-exec capabilities to generate multiarch-compatible package.install files. dh-exec is less necessary in compat 13, but that isn’t finished being rolled out yet to downstream releases like Ubuntu.

Here’s what i produced to make the cmake files show up in the liblastools-dev package:

#!/usr/bin/dh-exec
/usr/lib/${DEB_HOST_MULTIARCH}/cmake
/usr/include

Just mark the debian/liblastools-dev.install file as exectuable and dh-exec will take care of the rest.

A few callouts:

I used 3.0 (custom) in debian/source/format, but I can’t say that was absolutely necessary for this build setup
make sure you use include /usr/share/dpkg/default.mk in your makefile to get access to common packaging variables
Quilt (via dpkg-source) will automatically apply the patches listed by debian/patches/series, but that only works if you’re using importing from a .dsc file meaning somebody has already generated a debian package archive ahead of time.
Not all of us give a hoot about producing Debian hosting conformant packages with signing, etc, so you can pass --no-sign to dpkg-buildpackage to skip that step.
CMake build system isn’t set to produce shared libs by default so make sure to set -DBUILD_SHARED_LIBS=ON in override_dh_auto_configure
Since I wanted an atomically rebuild-able library I overrode the default build steps for dpkg-buildpackage
- dpkg-buildpackage -Tclean,build,binary,clean --no-sign
I still had to go through the original rigamarole of producing a base package, getting quilt/dquilt configured and producing a patch series, etc.

Here’s what I did to create the initial project structure to prepare for quilt patching:

$ wget -O lastools-0.1.0.tar.gz https://github.com/LAStools/LAStools/archive/master.tar.gz
$ mkdir lastools-0.1.0; cd lastools-0.1.0
$ dh_make -f ../lastools-0.1.0.tar.gz
$ tar -xaf ../lastools-0.1.0.tar.gz
$ dquilt new 1.patch
... apply changes
$ dquilt refresh
$ dquilt new 2.patch
$ dquilt refresh
... etc

This gave me the initial debian/ files to work with. From there, updating debian/rules, debian/control, debian/changelog, debian/source/format to produce a downloaded build was all that was necessary. All the other generated files can be removed except for debian/patches as this is what Quilt produces and you’ll want to re-apply them for your repeatable build.

You’ll want to make sure to manage your changelog, I don’t need to do that yet for this release so we’ll see how to get upstream comments in from the remote archive at a later date. In general, probably don’t care about this too much beyond just annotating releases

A neat trick for function pointer lambdas in C++

Wed, 16 Dec 2020 00:00:00 -0600

I just learned of a neat trick for getting a function pointer from a lambda in C++. This is not my code but I am passing it along for others should you happen upon my humble blog.

#include <cstdio>
#include <typeinfo>
int main ()
{
    auto x = [] {};
    auto y = +x;
    auto z = +[] {};
    std::printf ("%s %p\n", typeid (x).name (), x);
    std::printf ("%s %p\n", typeid (y).name (), y);
    std::printf ("%s %p\n", typeid (z).name (), z);
}

produces

$ ./test | c++filt -t
main::{lambda()#1} 0x7ffde2731538
void (*)() 0x401131
void (*)() 0x40115d

You can also use this trick with say decltype(+x) (using the above snippet for context) to generate a function pointer type.

Importantly, if you add a capture to x’s declaration a compile error will occur on y.

2020 US Election

Tue, 15 Dec 2020 00:00:00 -0600

Am I really expected to believe this travesty of an election?

Am I really expected to believe a man who underperformed his predecessors in every race except the 12 counties he needed at 4 AM the day after the election is legitimate?

Am I really expected to believe a man who can barely fill a parking lot with empty rental cars for his victory speech is the winner?

After countless tales of shenanigans on election night?

After months of dire warnings on mail-in fraud?

After numerous courts have ruled against the election night procedure changes?

After those court rulings were ignored and illegal procedure changes were performed anyway?

After numerous violations of Benford’s Law?

After voting machines were shown to violate state and federal law on error rates?

After audits showed voting machines were tampered with?

After countless documented counting errors that only ever went in one direction?

There are two things that keep the American Republic functioning today: Money and Voting.

As long as my money is stable I can secure wealth over time and improve my and my children’s lives.

As long as my vote counts, I can gather a smidgen of collective representation.

The government has decimated my money’s value over the last 100 years, and especially the last year with these insane stimulus bills. They have decimated my ability to earn an income with these insane lock-downs.

And now my vote has been made irrelevant with severe, blatant, and extensive cheating.

I have no hope of representation.

I have no faith in my ability to secure wealth via currency.

The legacy of this country’s founding has been destroyed. Prepare for war.

Codec for modern C++

Sun, 16 Aug 2020 00:00:00 -0500

I had some fun recently when working on my game.

I got to build a type-safe encoder decoder utility set that can encode and decode arbitrary types (with overload). It was an enjoyable experience to build, and I figure I’d just like to share it

Feel free to take this and use at your leisure, no copyright attribution is required.

Formalizing My Design Principles

Mon, 20 Apr 2020 00:00:00 -0500

I’ve been spending a bit of time thinking about what it is I do when designing interfaces. I definitely follow a few rules that I think are common:

immutable by default
composition over inheritance
dependency injection
single responsibility

But these don’t seem to capture my decision-making entirely, as other people don’t replicate my instructions with just these rules.

After spending some time thinking about it, I’ve decided to name some new rules that I follow.

Mental Offloading

Mental Offloading is the process by which you remove the need to consider what code is doing as you write it.

Methods should have clear inputs and outputs, be self-contained, and make no mutations to system state.

This last part of this statement is obviously impossible in the strictest sense, but it’s a goal rather than an outcome. The system state must be modifiable to make any program progress, so instead, consider that the function must not alter the behavior of the system after it has been called.

A print function should always print the same way.
A state machine must always consume it’s full language.
A class instance must be initialized completely before using it.
A class must allow for any order of initialization, and any order of method calls after initilization.
Don’t handle every case, make the cases you don’t want impossible instead.

The important takeaway is that the programmer should not have to have a mental model of program state on each line of code. Pass off work to subroutines liberally, but have strict minimal interfaces for those subroutines. Rather than writing a function with lots of parameters and tests and variability on output, write a function that does things one way, always the same way, is easy to test and verify; then when you consume it, the callsite should contain your mutations into and out of form.

Stateless classes, Stateful functions

As an extension of the above rule, tracking system state is the hardest part of software development. So make it easy on yourself and everyone else:

Constrain all state mutations to be within a single function scope.

You should consider your program as a series of idempotent “entry points” rather than a continuous state graph. Each entry point should progress the program state completely. Consider the principles of REST, where each HTTP verb has an explicit meaning, and server methods are idempotent.

Get - retrieve a document that exists
Put - update an existing document and return the result
Post - create a new document and return the result
Delete - destroy a document

Each of these methods maintain a consistent behavior no matter how many times called, or what order they are called in. Each method progresses the system state in some way, but no method causes the system to modify it’s behavior for any other invocation.

Your goal should be to write functions that either finish what they are doing or do nothing at all.

Detect error conditions in your function as early as possible and bail out without mutating the data.
Pre-calculate all parameters for state transforms ahead-of-time and only use at the last possible moment.
Mutate copies of data if there is any potential for error during execution, and apply the mutation later.

An example

Consider a class that does some stateful work:

class foo_t
{
public:
	void init (measurement_t const &measurement_);

	void updateModel (double timestamp_);
	void addMeasurements (vector<measurement_t> const &measurements_);
	void recalculateScores ();
	void calculateAverage ();

	measurement_t average () const;
};

The mental model of this class is complex, as you have to remember which order to call it’s methods in, what their side effects are, and whether or not you can use each method at a certain time. And while it may still fit inside of “SOLID” principles, dependency injection, composition over inheritnace, and immutable by default, the class is difficult to use.

Consider an updated class:

class foo_t
{
public:
	void init (measurement_t const &measurement_);

	void observe (double timestamp_, vector<measurement_t> const &measurements_)
	{
		updateModel (timestamp_);
		addMeasurements (measurements_);
		recalculateScores ();
		calculateAverage ();
	}

	measurement_t average () const;

private:
	void updateModel (double timestamp_);
	void addMeasurements (vector<measurement_t> const &measurements_);
	void recalculateScores ();
	void calculateAverage ();
};

Now, we have 3 operations:

initialize
mutate
query

As long as your write these operations to execute in any order, the programmer that uses these methods doesn’t need to track how they work, only that they will have an outcome. You have effectively offloaded the mental effort necessary to use your code to the code itself.

Steam and Vulkan - updated

Mon, 20 Jan 2020 00:00:00 -0600

Qt and Vulkan work fine.

Vulkan and Steam work fine.

Qt and Steam do not work fine.

Qt does some kind of weird behavior when inspecting the display layout that creates an early xcb window sized to the whole display. Steam catches this behavior and generates a Vulkan frame and adds input hooks to the early surface. Qt destroys this surface and generates a new one for your application’s widgets…

I can’t seem to get Steam to behave correctly with Vulkan, so I’ve ripped Qt Vulkan out and replaced it with a fully hand-rolled renderer on top of GLFW3. I’m still keeping my signals though, Qt can stay for that.

Steam and Vulkan

Fri, 05 Jul 2019 00:00:00 -0500

Just a note if anybody doesn’t know already:

To enable your Vulkan application to receive steam overlay support, make sure you add the Vulkan instance layer to your device initialization.

Here’s mine:

std::vector<char const *> const validationLayers = {
#ifndef NDEBUG
#ifndef Q_OS_ANDROID
    "VK_LAYER_LUNARG_standard_validation",
#else
    "VK_LAYER_GOOGLE_threading",
    "VK_LAYER_LUNARG_parameter_validation",
    "VK_LAYER_LUNARG_device_limits",
    "VK_LAYER_LUNARG_object_tracker",
    "VK_LAYER_LUNARG_image",
    "VK_LAYER_LUNARG_core_validation",
    "VK_LAYER_LUNARG_swapchain",
    "VK_LAYER_GOOGLE_unique_objects",
#endif
#endif
    "VK_LAYER_VALVE_steam_overlay_64",
    "VK_LAYER_VALVE_steam_overlay_32",
};

Qt Widgets and Vulkan

Tue, 02 Jul 2019 00:00:00 -0500

I had the hardest time getting Qt Widgets to be usable in the context of a Qt Vulkan Window, but I believe I’ve found a general method for using Qt Widgets on top of native drawing APIs.

The simplified version is:

Wrap your native drawing in a widget container (createWidgetContainer)
Create a central widget to attach child widgets to
Set the central widget as a child of your native drawing container
Add a QImage field to the central widget
Override paintEngine () to return the QImage field’s paintEngine ()
Upload the QImage to native rendering each frame as necessary

This of course has some overhead of copying image buffers around, especially to the GPU, as well as putting the updated texture in the correct form if you’re using Vulkan. But given the flexibility and power built-in to Qt Widgets, I definitely see the overhead being worth it.

I’ll give a little bit of sample code from my current project using Vulkan to demonstrate.

Let’s start with the central widget. I’m assuming you already have a robust renderer setup doing all the magic drawing you want in whatever way you please and now you want to put (alpha-enabled) widgets on top. If you’re just doing a viewport with widget support on the side, then the rest of this post won’t help you.

In your constructor make sure to include WA_NoSystemBackground and WA_TranslucentBackground. This should tell Qt not to expect to fill the widget background when drawing, and ensure that it uses a alpha channel when drawing as well. You’ll also want to call setAutoFillBackground (false) to keep Qt from filling the background with during draw with system colors.

centralWidget_t::centralWidget_t (QVulkanWindow *vulkan_) : m_vulkan (vulkan_)
{
	setAttribute (Qt::WA_NoSystemBackground);
	setAttribute (Qt::WA_TranslucentBackground);
	setAutoFillBackground (false);

	m_d->video->installEventFilter (this);
}

I added an event filter to track my Vulkan window’s resize event. This allows me to keep the central widget positioned at the window extents:

bool centralWidget_t::eventFilter (QObject *const watched_, QEvent *const event_)
{
	Q_UNUSED (watched_);

	if (!event_)
		return false;

	QSize newSize;

	switch (event_->type ())
	{
	case QEvent::Type::Resize:
		newSize = dynamic_cast<QResizeEvent *> (event_)->size ();
		break;
	default:
		return false;
	}

	resize (newSize);
	move (0, 0);

	return false;
}

You’ll also want to override the paintEngine () method of the central widget. This is necessary to keep Qt from trying to draw everything to framebuffer but still allow widget interactions. In this method, m_image is a QImage.

QPaintEngine *centralWidget_t::paintEngine () const
{
	return m_image.paintEngine ();
}

Finally, we need to get the frame uploaded and drawn. I’ll leave the transition, copy, and pipeline handling mechanisms as an excercise to the reader; if you’ve gotten this far these should be relatively simple.

void centralWidget_t::prepareDraw (VkCommandBuffer cmd_)
{
	auto const deviceFn = m_vulkan->deviceFn ();
	auto const device   = m_vulkan->device ();
	auto const frameId  = m_vulkan->currentFrame ();

	if (!m_img[frameId])
		return;

	m_frameDirty = clamp (m_frameDirty - 1, 0, m_video->concurrentFrameCount ());

	if (m_frameDirty <= 0)
		return;

	m_frame.fill (Qt::transparent);
	QPainter painter (&m_frame);
	render (&painter);

	unsigned width  = size ().width ();
	unsigned height = size ().height ();

	// data hasn't been mapped before
	if (!m_memMap[frameId])
		deviceFn->vkMapMemory (
		    device, m_txMem[frameId], 0, imageSize (size ()), 0, &m_memMap[frameId]);

	memcpy (m_memMap[frameId], m_frame.bits (), m_frame.sizeInBytes ());

	VkBufferImageCopy region{};
	region.bufferOffset                    = 0;
	region.bufferRowLength                 = 0;
	region.bufferImageHeight               = 0;
	region.imageSubresource.aspectMask     = VK_IMAGE_ASPECT_COLOR_BIT;
	region.imageSubresource.mipLevel       = 0;
	region.imageSubresource.baseArrayLayer = 0;
	region.imageSubresource.layerCount     = 1;
	region.imageOffset                     = {0, 0, 0};
	region.imageExtent                     = {width, height, 1};

	// see https://vulkan-tutorial.com for reference functions
	transitionImageLayout (
	    m_vulkan,
	    cmd_,
	    m_img[frameId],
	    VK_IMAGE_LAYOUT_UNDEFINED,
	    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL);

	deviceFn->vkCmdCopyBufferToImage (
	    cmd_,
	    m_txBuffer[frameId],
	    m_img[frameId],
	    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
	    1,
	    &region);

	transitionImageLayout (
	    m_vulkan,
	    cmd_,
	    m_img[frameId],
	    VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL,
	    VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL);
}

void centralWidget_t::draw (VkCommandBuffer const cmd_)
{
	auto const frameId = m_vulkan->currentFrame ();

	if (!m_img[frameId]) // this is a VkImage
		return;

	// if you're using QVulkanRenderer defaults, this method should record and execute a 
	// secondary command buffer using the default renderpass settings
	drawImage (cmd_, m_view[frameId], m_sampler[frameId]);
}

I know I haven’t shown you the class members or all the initialization. I’m going to justify this by saying you shouldn’t need to see them if you’ve studied the Vulkan API and vulkan-tutorial, and I don’t want you just copy-pasting this. I’ll eventually release this code under GPL anyway.

QVulkanRenderer

Now we need to ship commands off to the gpu. If you’re using QVulkanRenderer and QVulkanWindow defaults you’re probably already using the default renderpass which contains one subpass. If you’re not, have fun, you’re probably already ahead of me in terms of capabilities. In general your process should be:

Start your subpass draw commands
Prepare your widget texture transitions
Run your primary subpass secondary command buffers
Run your widget texture draw command buffer

That will look probably a little like this:

void startNextFrame () override
{
	auto const device      = m_video->device ();
	auto const deviceFn    = m_video->deviceFn ();
	m_frameId              = m_video->currentFrame ();
	auto const cmd         = m_video->currentCommandBuffer ();

	// start threaded drawing
	m_waitFrame[m_frameId] = false;
	emit m_video->draw ();

	// render widget while we wait (note this adds pipeline barriers on the raster step)
	m_video->centralWidget ()->prepareDraw (cmd);

	while (!m_waitFrame[m_frameId])
		std::this_thread::yield ();

	// begin drawing
	VkClearColorValue        clearColor = ;
	VkClearDepthStencilValue clearDS    = {2.0f, 0};
	VkClearValue             clearValues[3];
	memset (clearValues, 0, sizeof (clearValues));
	clearValues[0].color        = clearColor;
	clearValues[1].depthStencil = clearDS;
	clearValues[2].color        = clearColor;

	QSize const    sz     = m_video->swapChainImageSize ();
	unsigned const width  = sz.width ();
	unsigned const height = sz.height ();

	VkRenderPassBeginInfo rpBeginInfo{};
	memset (&rpBeginInfo, 0, sizeof (rpBeginInfo));
	rpBeginInfo.sType             = VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO;
	rpBeginInfo.renderPass        = m_video->defaultRenderPass ();
	rpBeginInfo.framebuffer       = m_video->currentFramebuffer ();
	rpBeginInfo.renderArea.offset = {0, 0};
	rpBeginInfo.renderArea.extent = {width, height};
	rpBeginInfo.clearValueCount = 3;
	rpBeginInfo.pClearValues    = clearValues;

	deviceFn->vkCmdBeginRenderPass (
	    cmd, &rpBeginInfo, VK_SUBPASS_CONTENTS_SECONDARY_COMMAND_BUFFERS);
	
	// submit our command buffers
	if (m_commandBufferList.size () > 0)
		deviceFn->vkCmdExecuteCommands (
		    cmd,
		    static_cast<uint32_t> (m_commandBufferList.size ()),
		    m_commandBufferList.data ());

	// draw the widget onto a view-aligned quad after everything else
	m_video->centralWidget ()->draw (cmd);

	deviceFn->vkCmdEndRenderPass (cmd);

	m_video->frameReady ();
	m_video->requestUpdate ();
}

Main Window

Somehwere in your main, you’ll need to capture your QVulkanWindow into a widget container using QWidget::createWindowContainer ().

Here’s the basic process I followed:

int main (int argc, char *argv[])
{
	QApplication app (argc, argv);

	auto const myVulkan = new myQVulkanWindow ();
	auto const videoWidget = QWidget::createWindowContainer (myVulkan);

	auto const centralWidget = new centralWidget_t ();
	centralWidget->setParent (videoWidget);

	centralWidget->setLayout (new QVBoxLayout ());
	centralWidget->layout ()->addWidget (new mainMenu_t{});

	videoWidget->resize (640, 480);
	videoWidget->show ();

	return app.exec ();
}

And here we go!

A thread-safe factory template

Fri, 24 May 2019 00:00:00 -0500

I was playing around with my multi-threaded vulkan renderer today and I managed to build a nice tool for managing my shared resources (mesh, texture, pipeline, etc. data).

template <typename T>
class factory_t
{
public:
	std::shared_ptr<T> create (std::string const key_, std::function<std::shared_ptr<T> ()> create_)
	{
		std::unique_lock<std::mutex> mapLock{m_mapGuard};

		auto &data_wk = m_map[key_];
		mapLock.unlock ();

		std::lock_guard<std::mutex> dataLock{std::get<0> (data_wk)};

		std::shared_ptr<T> data = std::get<1> (data_wk).lock ();

		if (!data)
		{
			data = create_ ();

			std::get<1> (data_wk) = data;
		}

		return data;
	}

	std::mutex                                                      m_mapGuard;
	std::map<std::string, std::tuple<std::mutex, std::weak_ptr<T>>> m_map;
};

Just provide a key and make sure your create_ functor is thread-safe and you’ll get per-key factory allocations with thread safety.

If you want to use it, license it under GPL, LGPL, or MIT and maybe say nice things about me to your friends. Happy coding!

A Few Basic Principles For System Design (Part 3)

Mon, 06 Nov 2017 00:00:00 -0600

Building complex systems is never simple, but there are a few things you can do to make your life a bit easier. One of the hardest parts in designing these things is to make them testable, so that work tomorrow doesn’t break work today. I’ll go over a few concepts to make life easier when doing this.

Immutability

One easily applied hard-and-fast rule you can make for yourself and any code you write is to take advantage of immutability.

If we look up immutability, we see that it means something cannot be changed. Applied here, we mean to never mutate input. There are other ways to apply this, but the simplest rule is no mutation.

If we take the code:

int main() {
	string to_print = "hello, world!";
	modify_string(to_print);
	cout << to_print << endl;
	return 0;
}

we can see one glaring area of needed maintenance. If modify_string’s operation should ever change, we need to be absolutely sure that our modifications don’t influence the program’s correctness outside of modify_string.

Here’s a potential implementation of modify_string:

void modify_string(string& input) {
	for(int i=0; i<string.size(); i++)
		if(string[i] == ',')
			string[i] = '.';
}

This implementation overwrites the calling function’s understanding of the data, making this function and the caller very tightly coupled. If I am to call modify_string from anywhere else in the program, I must be absolutely aware of the preconditions and postconditions of it’s execution, and replicate any setup procedures from the canonical use.

In short:

Code duplication
Tight coupling
Difficulty optimizing
High knowledge overhead

Let’s tweak this function to make it re-useable

int main() {
	string to_print = "hello, world!";
	
	cout << modify_string(to_print) << endl;
	
	return 0;
}

string modify_string(const string& input) {
	string copy = input;
	for(int i=0; i<copy.size(); i++)
		if(copy[i] == ',')
			copy[i] = '.'; // input is a copy, so safe
	return input;
}

Now, to_print never changes. If we need to mutate it, we just assign it back the result of modify_string. No callers need to know the post-conditions of their inputs because the inputs don’t change. If the function has some precondition incantation that must be run to prepare it’s inputs, we can make an immutable function to do just that, and pass it in directly. Should modify_string ever change, we are fully safe from the result in all callers and thus our maintenance burden has decreased significantly.

There are practically no situations where parameter mutation is beneficial for the maintenance overhead it creates. The one situation is memory pressure. Cloning an object over and over can drastically reduce performance, and many immutable-first languages optimize these clone operations out where possible. If you absolutely MUST mutate inside a function, make sure to be aware of the following conditions:

Thread safety - the mutated parameter must not be shared, and if some property of it is mutated directly, re-factor your code to mutate that portion alone in a thread-safe manner.
Conciseness - your mutation should be very small and explicit. Dozens of small mutations is far easier to reason about than one large multi-branch multi-loop recursive operation
Unique - your mutation should be an operation that only happens in this specific call-chain. If it happens in many places, consider a class member that does the mutation for you and hiding the mutated data behind an explicit interface. This reduces the chance of inflicting duplicate code on other callers.
Final - your mutation should be the last change that happens to this input, and potentially the last action that happens to this input. Callers of your mutating function shouldn’t rely on the function having side-effects or post-conditions on inputs for them to continue operating.
Obviousness - many languages support the concept of out-bound parameters, C and C++ with &, C# with ref and out. Consider annotating the value as explicitly being an outbound mutation so callers can know to expect it.

A strong point to remember is that every function you write is an interface you or someone else will have to deal with in the future, without a cup of coffee, with haranguing managers and impending deadlines, with a hangover, etc. Try to make your functions as trivial to understand and reason about as possible, and try to never make future you spend 3 hours stepping through code with the debugger to figure out what just happend.