►
From YouTube: Evolving API design in Rust — Simon Nicholas Heath
Description
As Rust is a young language containing many innovative features, questions about how to structure Rust libraries and API's are common. Heavy use of metaprogramming and trait constraints can make libraries hard to understand and use, but also bring great power to reason about programs at compile-time. How do you design a library that exploits the power of Rust without making new users say 'This is way too complicated to bother with'? We will discuss these issues using an existing Rust crate as a case study in both designing an API and how it is influenced by the API decisions of the crates it uses as dependencies.
---
Simon is a recovering geologist who has always been interested in programming and a general language nerd, and now works as a software engineering consultant. He started using Rust seriously shortly after the 1.0 release and is interested in using it in video games, operating systems and distributed network infrastructure.
A
It
is
based
on
a
Lua
game
framework
called
love
2d,
which
also
has
a
similar
goal
of
making
2d
games
easily,
which
is
to
say
that
I
went
through
the
love
to
dapi
docs
function
by
function
and
wrote
everything
in
rust,
because
I
didn't
really
have
a
great
plan
for
how
to
make
a
good
2d
great
game.
Engine
I
just
wanted
something
that
was
simple
and
would
work
and
was
easy
to
use.
So
I
knew
love
was
simple
and
worked
and
I've
used
it
before.
So
there
we
go
GG.
A
It's
nothing
so
far,
there's
anything
like
super
huge
or
complicated
besides
Emeraude,
which
is
this
one
which
has
been
worked
on
since
before
I
started,
working
on
rust,
but
hopefully
someday
I'll
actually
get
to
write
games
in
GG
easy
as
well.
That's
my
that's
my
goal
for
2019.
So
to
do
all
this
stuff.
A
A
It
has
to
actually
be
able
to
use
all
of
these
crates
successfully,
and
so
I
have
gotten
to
be
very
good
friends
with
some
of
the
maintainer
of
these
crates,
because
I
would
keep
submitting
bug,
reports
or
I
would
keep
saying.
I
need
to
be
able
to
do
X,
Y
can't.
How
do
I
do
X
and
usually
they
tell
me
in
life-
is
good,
but
I
wanted
to
do
this.
A
Talk
because
I
also
hang
out
on
Reddit
and
IRC
a
lot,
and
probably
too
much
and
I
keep
seeing
things
like
this,
so
everyone
who
first
learns
to
rust
and
write
something
big
has
to
ask
for
advice
on
it,
and
so
it
was.
It
was
weird
because
I
don't
see
this
a
lot
in
like
Python
or
C,
sharp
or
whatever.
A
Maybe
the
world
would
be
a
better
place
if
people
did
do
this
in
those
languages,
but
either
way,
people
who
learn
rust
seem
to
have
trouble
figuring
out
how
to
write
rust,
api's,
or
at
least
they
have
anxiety
about
writing
rust
api's.
They
keep
asking
how
do
I
write,
idiomatic
rust,
and
so
that's
what
I
want
to
talk
about.
So
how
do
we
design
a
good
API
in
rust?
In
my
case,
I
didn't
have
to
design
an
API
I,
just
copied
an
API
and
made
it
rusty.
A
So
that
was,
let's
take
a
look
at
the
API
I
copied
it
a
little
bit
but
I'm
going
to
start
with
some
GG
easy
examples
and
then
I'm
going
to
look
at
some
of
the
other
crates
that
GG
easy
uses
and
how
those
sort
of
look
from
an
end-user
perspective
and
what's
good
about
them
and
what's
bad
about
them.
So
here
is
a
very
simple
love,
2d
game.
It's
all
in
Lua,
I,
don't
know
how
many
people
out
there
know
Lua,
but
we
have
some
functions.
A
We
have
load
update
and
draw
which
are
the
sort
of
fundamental
parts
of
your
game.
We
have
a
global
player
which
is
just
a
table
dict.
Essentially
that's
my
Python
showing
through,
and
we
have
update
detects
if
you
are
pressing
buttons
and
changes
the
world
state.
If
you
are
and
draw
draw
stuff
I'm
great-
and
these
are
basically
callbacks
that
are
loaded
by
the
Lua
interpreter
and
love
basically
has
a
version
of
the
interpreter
that
is
built
with
a
bunch
of
libraries
and
looks
for
these
callbacks
and
loads
them
and
run
to
your
game.
A
So
this
is
pretty
different
from
how
rust
works.
I
mean
there's
no
curly
braces
at
all
it's,
but
we
have
these
sort
of
magic
callbacks
that
the
interpreter
looks
for
it's
dynamically
typed,
there's
mutable
state
everywhere.
So
it's
it's
kind
of
I
didn't
even
know
if
it
was
going
to
be
possible
to
make
this
in
rust.
I
was
like
well,
maybe
I
mean
look
at
just
the
draw
the
love
2d
draw
function.
We
have
four
different
overloads
for
the
draw
function:
I
like
your
expression
to
them.
Responding
to
this.
A
You
can
have
a
transform,
which
is
a
structure
that
basically
bundles
up
all
of
the
drawing
parameters,
or
you
can
just
list
all
the
drawing
parameters
for
that
are
possible
individually,
and
it
also
turns
out
that
you
can
actually
omit
the
ones
at
the
end
and
they'll
just
default
to
0
or
1
or
whatever
is
appropriate,
and
so
you
can
just
leave
all
of
those
off
and
just
have
x
and
y
and
r,
and
it
works
fine.
So
I
was
I,
was
kind
of
like
looking
at
this
and
saying
well.
A
I
just
want
to
make
something
work
so
worst
case.
I'll
just
make
a
separate
function
for
each
of
these
variants,
and
so
I
started
with
that
and
I
sort
of
squished
it
together
and
got
something
like
this.
So
we
have
a
struct
that
has
all
the
draw
parameters
in
it
that
you
can't
have,
and
we
have
a
function
that
takes
a
drawable
object
and
draw
params
and
a
context
which
I
just
hold
on
to
the
graphics
contacts
date
and
appears
everywhere,
and
it
draws
it
based
on
whatever
parameters
you
give
it
and
then
well.
A
Okay,
we
have
a
simplified
function
that
just
takes
a
destination
point
under
a
rotation,
and
you
can
use
that.
If
that's
all
you
need-
and
if
you
need
the
full
power
function,
then
you
can
use
that
instead,
it
was
like
okay,
yeah,
fine,
eventually,
I
discovered
that
the
default
rate
and
the
struct
update
syntax
exists,
and
you
can
do
something
like
this,
which
actually
is
halfway
decent.
It's
not
great,
it's
not
terrible,
but
it
works.
A
It's
it's
not
too
pretty
I,
don't
I,
never
really
liked
it,
but
something
that
I
realized
as
time
went
on
is
that
GG
ez
is
an
opinionated
framework,
and
so
lots
of
people
have
opinions
about
it.
Whenever
they
try
to
use
it,
it's
actually
fairly
low-level,
it
doesn't
provide
animations,
it
doesn't
provide
a
physics
engine,
but-
and
so
everyone
says-
oh,
why
don't
you
do
it
this
way
or
why
don't
you
add
this
or
why
don't
you
not
add
that?
A
But
nobody
in
the
last,
like
two
and
a
half
years
or
whatever,
has
actually
complained
about
this
horrible
hack.
It's
not
a
problem
like
it's.
It
actually
has
quite
a
few
advantages.
It's
simple
like
even
a
new,
even
the
most
basic
rust
programmer,
can
understand.
It
is
completely
obvious.
What's
going
on
and
like
where
the
data
is
coming
from,
where
it's
going
and
where
it's
used
and
with
this
my
syntax,
it's
even
not
too
terrible,
so
it
works.
A
So
the
harder
case
was
dealing
with
love
to
DS
sort
of
callback
structure
and
I
ended
up
starting
with
something
like
this.
Where
we
had
a
trait
called
game,
state
and
I
should
have
cut
out
all
the
inconvenient
code,
but
it
provides
load,
update
and
draw
methods
that
are
just
like
Lewis,
Orlov
to
DS,
load,
update
and
draw
methods,
and
then
down
here
you
have
this
game
struct.
A
That
is
generic
on
your
the
type
that
you
implemented
the
game
state
trait
for
and
it
just
creates
your
game
state
by
calling
the
load
method,
and
then
it
has
an
event
loop
inside
it
that
calls
update
and
draw
and
takes
keyboard
events
and
all
that
stuff,
and
so
this
is
the
closest
I
could
get
to
something
that
looks
like
love
2d,
where
it
just
had
these
magic
callbacks.
That
did
everything
for
you
and
it
sucked
nobody
hated
it
look
or
nobody
liked
it.
I
didn't
like
it.
I
got
tons
of
questions
like
oh.
A
A
Well
it
uses
you
have
to
annotate
it
with
that
generic
parameter
and
like
howdy
where's,
the
context
get
created
well,
it
gets
created
in
the
game
and
like
it
was
just
complicated
and
nasty,
and
eventually
I
wanted
to
be
able
to
even
like
take
apart
the
event
loop
and
let
the
user
sort
of
write
their
own
with
their
own
update
functionality
if
they
really
wanted
to
because
love
2d
does
allow
you
to
do
that.
So
eventually,
I
ended
up
with
this,
which
is
kind
of
similar.
A
We
have
a
event
handle
or
trait
it
defines
update
and
draw
methods,
but
the
main
the
gain
state
is
just
a
struct.
You
create
and
there's
nothing
special
about
it.
You
create
a
context
which
is
sort
of
the
handle
to
all
the
GG
easy
library
functions
like
it
handles
the
sound
state,
the
window
state,
it
talks
to
the
operating
system
etc,
and
you
have
this
event
that
run
or
call
and
run
function,
which
is
literally
what
you
would
just
write.
A
It's
a
while
loop
that
pulls
the
operating
system
for
events,
calls
event
handler,
update
and
then
calls
event
handler
draw,
and
it
just
does
that
and
now
we
by
making
by
trying
to
do
less
magic,
everything
becomes
way
better
and
so
and
I
didn't
like
it
was
like
this.
This
doesn't
really
look
rusty.
This
is
kind
of
dumb
as
a
pile
of
bricks,
but
how
do
we
design
a
good,
API
and
rust
everything?
A
good
API
is
still
a
good
API
in
rust.
That
was
the
sort
of
what
I
figured
out.
A
Lou
loved
2d
started
off
with
a
pretty
good
API.
I
turned
it
into
rust,
and
it's
still
a
good
API
rust,
doesn't
add
or
remove
anything
too
magical
from
it
and
when
it
down
keep
it
simple.
I,
like
the
term
complexity
budget,
that
the
last
talk
used
because
having
the
putting
the
but
putting
my
conflict
but
into
trying
to
make
it
look
exactly
like
a
Lua
API
wasn't
worth
the
extra
compact,
so
another
problem
that
I
deal
have
often
when
people
are
trying
to
get
into
rust.
A
Gamedev
is
that
some
popular
crates
are
very
hairy,
so
they
say
well
what
are
my
options
for
drawing
graphics
and
someone
mentions
GFX
RS,
which
is
awesome
and
which
love
2d
uses,
and
they
go
to
the
docks,
and
they
see
this
now.
I,
don't
know
about
you,
like,
usually
I
call
it
quits.
After
only
like
seven
or
eight
associated
types.
Here
we
have
twelve
or
they
say,
okay.
Well,
how
do
I
do
matrix,
math
well,
look
at
an
algebra,
and
they
see
this
like
this
is
this
is
the
matrix
type?
A
This
is
what's
even
going
on
here.
We
it's
almost
impossible
to
read
when
I
see
stuff
like
this
I
call
it
trait
salad,
because
it's
just
a
pile
of
different
stuff,
all
mixed
up,
and
you
can't
make
heads
or
tails
of
it.
But
if
you're
like
trying
to
learn
rust-
and
you
come
at
this-
and
this
is
what
you
see
then
you
obviously
the
Creator
is
this
guy-
who
either
is
just
a
mentat?
A
A
A
So,
what's
going
act
what's
actually
going
on
here,
I
we
have
a
bunch
of
traits.
They
all
have
really
complicated
bounds
like
we
have
one
here
called
abstract,
magma
I,
usually
think
of
this.
When
I
see
that
or
maybe
this,
however,
it
turns
out
that
what
I
should
have
been
thinking
of
is
this:
it's
a
math
term,
and
so
what
an
algebra
is
doing
is
teaching
the
RUS
compiler,
how
to
do
fundamental
math
by
encoding
it
in
the
type
system
and
that's
not
something
that
would
have
ever
occurred
to
me
to
do.
A
But
it
also
means
that
it
completely
rules
out
a
lot
of
math
errors
at
compile
time
you
can't
like,
if
you
have
a
transform
vector
and
the
scale
vector
you
can't
add
them
together.
The
type
checker
catches
it
and
GFX
is
similar.
It's
doing
something
kind
of
like
that,
trying
to
encode
the
state
of
a
graphics
card
in
the
type
system
which
is
really
complicated
in
low
level,
but
you
end
up.
A
It
ends
up
catching
a
lot
of
bugs,
so
these
aren't
bad
api's,
they're,
just
very
sophisticated
and
specific
and
low-level
and
are
geared
towards
a
certain
type
of
use.
Case.
I've
talked
to
people
who
have
a
formal,
math
background
and
use
an
algebra,
and
they
love
it
like
they
don't
see
this
Magma
they,
but
they
all
of
this
pops
out
at
them
and
they're
like
oh
I,
know
how
everything
fits
together,
so
it
the
next
lesson
is
know
your
audience.
A
A
So
also
as
an
audience
know
your
tools,
it's
a
lot
easier
to
understand
why
an
API
is
the
way
it
is,
and
what,
where
to
look,
when
you
need
some
functionality
when
you
know
who
the
writer
is
making
it
for?
Maybe
it's
not
for
you.
Maybe
it's
something
you
can
learn,
but
either
way,
so
we've
discovered
that
API
design
in
rust
in
horror
is
hard.
It's
hard
in
any
language.
A
Rust
seems
to
make
it
trickier,
though,
why
do
people
get
such
anxiety
about
it
and
what
can
we
do
to
make
it
better
well
in
rust,
API
and
this
features
are
actually
really
nasty.
This
is
true
in
any
language
like
Java
or
Python
or
whatever,
but
rust
is
good
at
making
things
subtly
terrible
in
ways
that
aren't
obvious
to
people
who
don't
know
rust
very
well,
for
instance,
Gigi
easy.
A
Let
has
a
sub-module
for
loading
resources
from
file
paths
without
and
keeping
the
files
in
some
platform,
specific
location,
that's
different
on
whatever
on
Windows
on
Mac
OS
X
on
whatever,
and
so
it
uses
a
crate
to
like
just
ask
the
operating
system,
what
paths
it
should
use
and
it's
called
the
crate.
It's
called
actors
and
it
works
basically
like
this.
A
So
the
API
is
this:
it's
there's
more
than
this,
but
this
is
the
part
that
Gigi's
you
uses
the
most,
and
so
we
have
a
struct
and
we
have
a
method
and
the
struct
has
some
static
strings
and
everything
is
good
and
so
I
wanted,
at
one
point,
to
write
a
program
that
loaded
these
paths
from
a
config
file
or
something
and
so
I
had
something
like
this.
We
have
author
and
app
name
which
are
own
strings
and
we
feed
weight.
A
We
feed
them
into
app
info,
which
is
static,
string
slices
except
these
are
own
strings,
but
these
are
static,
string
slices.
You
can't
get
there
from
here.
How
do
you
do
it?
Well,
you
can
probably
figure
it
like
you
go
on
IRC
and
you
ask:
how
do
you
turn
a
own
string
into
a
static,
static
string
slice
and
someone
will
say:
well,
you
can
probably
do
it
with
unsafe,
but
we
don't
like
doing
that,
because
the
point
of
unsafe
is
that
you
never
need
to
use
it.
A
A
That's
sort
of
been
overlaid
on
top
of
it,
and
this
is
handy
for
games,
because,
especially
if
you
want
a
game,
that's
moddable
or
something
you
can
have
all
the
sort
of
formal
game
resources
and
one
zip
file.
And
then
you
can
have
a
mod
that
just
sort
of
replaces
a
few
of
them
either
in
a
zip
file
or
in
a
directory,
and
it's
nice,
and
we
just
have
I
wanted
to
just
have
a
trade.
A
The
file
system
be
a
trade
object
that
exposed
a
few
methods
and
we
just
have
a
Veck
and
we
just
look
at
which
ones
we
just
look
through
each
of
them
in
turn
and
use
the
first
one
that
has
a
file
great,
so
I
found
a
crate
that
looks
like
it
head.
Does
this
and
is
called-
and
it
has
a
trait
like
this
and
it's
called
VFS,
and
so
we
have
the
path
which
this
crate
is
the
the
path
user.
A
It
uses
the
path
as
the
entry
point
kind
of
like
you,
you
use
path,
and
then
you
open
a
file
and
it's
very
object
oriented,
but
it
works.
Ok
and
then
we
have
a
associated
file,
it
metadata
type.
And
then
you
create
a
path
through
this
method
on
the
trade,
and
it
takes
some
thing
that
can
be
turned
into
a
string
and
gives
you
the
path
type
for
that
trait.
A
Well,
hang
on
I
want
to
trade
objects,
and
this
has
a
generic
parameter
with
a
trait
bound,
but
you
can't
turn
that
into
trade
objects,
because
the
trade
object
needs
a
V
table
and
this
will
make
one.
The
compiler
will
make
one
version
of
the
path
method
for
each
type
that
you
specialize
it
with,
and
so
you
can't
you
can't
make
a
trade
object
from
that.
A
A
This
is
a
design
decision
that
had
unexpected
consequences.
Unfortunately,
I
don't
really
have
a
great
answer
to
this
one.
Besides
iterate,
because
people
will
always
come
up
with
interesting
use
cases
that
you
never
thought
of.
I've
spent
the
last
two
weeks
with
some
trying
to
get
GG
easy
to
work
on
iOS,
because
someone
really
wanted
it
too,
and
I
never
really
considered
doing
that
before.
A
A
It's
you
like
rust
is
great
because
you
have
cargo,
everyone
tends
to
use
semantic
versioning
and
it
has
good
encapsulation.
And
so,
if
you
make
an
update,
an
update
to
your
crate
like
futures
or
something
and
people
don't
like
it,
that's
fine,
they
just
use
the
old
version,
and
it's
no.
It's
no
problem.
So
everything
you
know
about.
Api
design
still
works
in
rust.
If
you
can
make
a
function
that
takes
borrowed
types
and
returns
as
a
result,
when
necessary,
then
you're
writing
idiomatic
Rus
code.
It
doesn't
matter
how
non
fancy
it
is.