go/doc/go1.10.html at go1.10 · dominicbarnes/go

Repository navigation

History

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

<!--{

"Title": "Go 1.10 Release Notes",

"Path": "/doc/go1.10",

"Template": true

}-->

<!--

NOTE: In this document and others in this directory, the convention is to

set fixed-width phrases with non-fixed-width spaces, as in

<code>hello</code> <code>world</code>.

Do not send CLs removing the interior tags from such phrases.

-->

<style>

ul li { margin: 0.5em 0; }

</style>

<h2 id="introduction">Introduction to Go 1.10</h2>

The latest Go release, version 1.10, arrives six months after <a href="go1.9">Go 1.9</a>.

Most of its changes are in the implementation of the toolchain, runtime, and libraries.

As always, the release maintains the Go 1 <a href="/doc/go1compat.html">promise of compatibility</a>.

We expect almost all Go programs to continue to compile and run as before.

This release improves <a href="#build">caching of built packages</a>,

adds <a href="#test">caching of successful test results</a>,

runs <a href="#test-vet">vet automatically during tests</a>,

and

permits <a href="#cgo">passing string values directly between Go and C using cgo</a>.

A new <a href="#cgo">compiler option whitelist</a> may cause

unexpected <a href="https://golang.org/s/invalidflag"><code>invalid

flag</code></a> errors in code that built successfully with older

releases.

<h2 id="language">Changes to the language</h2>

There are no significant changes to the language specification.

A corner case involving shifts by untyped constants has been clarified,

and as a result the compilers have been updated to allow the index expression

<code>x[1.0</code> <code><<</code> <code>s]</code> where <code>s</code> is an untyped constant;

the <a href="/pkg/go/types/">go/types</a> package already did.

The grammar for method expressions has been updated to relax the

syntax to allow any type expression as a receiver;

this matches what the compilers were already implementing.

For example, <code>struct{io.Reader}.Read</code> is a valid, if unusual,

method expression that the compilers already accepted and is

now permitted by the language grammar.

<h2 id="ports">Ports</h2>

There are no new supported operating systems or processor architectures in this release.

Most of the work has focused on strengthening the support for existing ports,

in particular <a href="#asm">new instructions in the assembler</a>

and improvements to the code generated by the compilers.

As <a href="go1.9#freebsd">announced in the Go 1.9 release notes</a>,

Go 1.10 now requires FreeBSD 10.3 or later;

support for FreeBSD 9.3 has been removed.

Go now runs on NetBSD again but requires the unreleased NetBSD 8.

Only <code>GOARCH</code> <code>amd64</code> and <code>386</code> have

been fixed. The <code>arm</code> port is still broken.

On 32-bit MIPS systems, the new environment variable settings

<code>GOMIPS=hardfloat</code> (the default) and

<code>GOMIPS=softfloat</code> select whether to use

hardware instructions or software emulation for floating-point computations.

Go 1.10 is the last release that will run on OpenBSD 6.0.

Go 1.11 will require OpenBSD 6.2.

Go 1.10 is the last release that will run on OS X 10.8 Mountain Lion or OS X 10.9 Mavericks.

Go 1.11 will require OS X 10.10 Yosemite or later.

Go 1.10 is the last release that will run on Windows XP or Windows Vista.

Go 1.11 will require Windows 7 or later.

<h2 id="tools">Tools</h2>

<h3 id="goroot">Default GOROOT & GOTMPDIR</h3>

If the environment variable <code>$GOROOT</code> is unset,

the go tool previously used the default <code>GOROOT</code>

set during toolchain compilation.

Now, before falling back to that default, the go tool attempts to

deduce <code>GOROOT</code> from its own executable path.

This allows binary distributions to be unpacked anywhere in the

file system and then be used without setting <code>GOROOT</code>

explicitly.

By default, the go tool creates its temporary files and directories

in the system temporary directory (for example, <code>$TMPDIR</code> on Unix).

If the new environment variable <code>$GOTMPDIR</code> is set,

the go tool will creates its temporary files and directories in that directory instead.

<h3 id="build">Build & Install</h3>

The <code>go</code> <code>build</code> command now detects out-of-date packages

purely based on the content of source files, specified build flags, and metadata stored in the compiled packages.

Modification times are no longer consulted or relevant.

The old advice to add <code>-a</code> to force a rebuild in cases where

the modification times were misleading for one reason or another

(for example, changes in build flags) is no longer necessary:

builds now always detect when packages must be rebuilt.

(If you observe otherwise, please file a bug.)

The <code>go</code> <code>build</code> <code>-asmflags</code>, <code>-gcflags</code>, <code>-gccgoflags</code>, and <code>-ldflags</code> options

now apply by default only to the packages listed directly on the command line.

For example, <code>go</code> <code>build</code> <code>-gcflags=-m</code> <code>mypkg</code>

passes the compiler the <code>-m</code> flag when building <code>mypkg</code>

but not its dependencies.

The new, more general form <code>-asmflags=pattern=flags</code> (and similarly for the others)

applies the <code>flags</code> only to the packages matching the pattern.

For example: <code>go</code> <code>install</code> <code>-ldflags=cmd/gofmt=-X=main.version=1.2.3</code> <code>cmd/...</code>

installs all the commands matching <code>cmd/...</code> but only applies the <code>-X</code> option

to the linker flags for <code>cmd/gofmt</code>.

For more details, see <a href="/cmd/go/#hdr-Compile_packages_and_dependencies"><code>go</code> <code>help</code> <code>build</code></a>.

The <code>go</code> <code>build</code> command now maintains a cache of

recently built packages, separate from the installed packages in <code>$GOROOT/pkg</code> or <code>$GOPATH/pkg</code>.

The effect of the cache should be to speed builds that do not explicitly install packages

or when switching between different copies of source code (for example, when changing

back and forth between different branches in a version control system).

The old advice to add the <code>-i</code> flag for speed, as in <code>go</code> <code>build</code> <code>-i</code>

or <code>go</code> <code>test</code> <code>-i</code>,

is no longer necessary: builds run just as fast without <code>-i</code>.

For more details, see <a href="/cmd/go/#hdr-Build_and_test_caching"><code>go</code> <code>help</code> <code>cache</code></a>.

The <code>go</code> <code>install</code> command now installs only the

packages and commands listed directly on the command line.

For example, <code>go</code> <code>install</code> <code>cmd/gofmt</code>

installs the gofmt program but not any of the packages on which it depends.

The new build cache makes future commands still run as quickly as if the

dependencies had been installed.

To force the installation of dependencies, use the new

<code>go</code> <code>install</code> <code>-i</code> flag.

Installing dependency packages should not be necessary in general,

and the very concept of installed packages may disappear in a future release.

Many details of the <code>go</code> <code>build</code> implementation have changed to support these improvements.

One new requirement implied by these changes is that

binary-only packages must now declare accurate import blocks in their

stub source code, so that those imports can be made available when

linking a program using the binary-only package.

For more details, see <a href="/cmd/go/#hdr-File_types"><code>go</code> <code>help</code> <code>filetype</code></a>.

The <code>go</code> <code>test</code> command now caches test results:

if the test executable and command line match a previous run

and the files and environment variables consulted by that run

have not changed either, <code>go</code> <code>test</code> will print

the previous test output, replacing the elapsed time with the string “(cached).”

Test caching applies only to successful test results;

only to <code>go</code> <code>test</code>

commands with an explicit list of packages; and

only to command lines using a subset of the

<code>-cpu</code>, <code>-list</code>, <code>-parallel</code>,

<code>-run</code>, <code>-short</code>, and <code>-v</code> test flags.

The idiomatic way to bypass test caching is to use <code>-count=1</code>.

The <code>go</code> <code>test</code> command now automatically runs

<code>go</code> <code>vet</code> on the package being tested,

to identify significant problems before running the test.

Any such problems are treated like build errors and prevent execution of the test.

Only a high-confidence subset of the available <code>go</code> <code>vet</code>

checks are enabled for this automatic check.

To disable the running of <code>go</code> <code>vet</code>, use

<code>go</code> <code>test</code> <code>-vet=off</code>.

The <code>go</code> <code>test</code> <code>-coverpkg</code> flag now

interprets its argument as a comma-separated list of patterns to match against

the dependencies of each test, not as a list of packages to load anew.

For example, <code>go</code> <code>test</code> <code>-coverpkg=all</code>

is now a meaningful way to run a test with coverage enabled for the test package

and all its dependencies.

Also, the <code>go</code> <code>test</code> <code>-coverprofile</code> option is now

supported when running multiple tests.

In case of failure due to timeout, tests are now more likely to write their profiles before exiting.

The <code>go</code> <code>test</code> command now always

merges the standard output and standard error from a given test binary execution

and writes both to <code>go</code> <code>test</code>'s standard output.

In past releases, <code>go</code> <code>test</code> only applied this

merging most of the time.

The <code>go</code> <code>test</code> <code>-v</code> output

now includes <code>PAUSE</code> and <code>CONT</code> status update

lines to mark when <a href="/pkg/testing/#T.Parallel">parallel tests</a> pause and continue.

The new <code>go</code> <code>test</code> <code>-failfast</code> flag

disables running additional tests after any test fails.

Note that tests running in parallel with the failing test are allowed to complete.

Finally, the new <code>go</code> <code>test</code> <code>-json</code> flag

filters test output through the new command

to produce a machine-readable JSON-formatted description of test execution.

This allows the creation of rich presentations of test execution

in IDEs and other tools.

For more details about all these changes,

see <a href="/cmd/go/#hdr-Test_packages"><code>go</code> <code>help</code> <code>test</code></a>

and the <a href="/cmd/test2json/">test2json documentation</a>.

Options specified by cgo using <code>#cgo CFLAGS</code> and the like

are now checked against a whitelist of permitted options.

This closes a security hole in which a downloaded package uses

compiler options like

<code>-fplugin</code>

to run arbitrary code on the machine where it is being built.

This can cause a build error such as <code>invalid flag in #cgo CFLAGS</code>.

For more background, and how to handle this error, see

<a href="https://golang.org/s/invalidflag">https://golang.org/s/invalidflag</a>.

Cgo now implements a C typedef like “<code>typedef</code> <code>X</code> <code>Y</code>” using a Go type alias,

so that Go code may use the types <code>C.X</code> and <code>C.Y</code> interchangeably.

It also now supports the use of niladic function-like macros.

Also, the documentation has been updated to clarify that

Go structs and Go arrays are not supported in the type signatures of cgo-exported functions.

Cgo now supports direct access to Go string values from C.

Functions in the C preamble may use the type <code>_GoString_</code>

to accept a Go string as an argument.

C code may call <code>_GoStringLen</code> and <code>_GoStringPtr</code>

for direct access to the contents of the string.

A value of type <code>_GoString_</code>

may be passed in a call to an exported Go function that takes an argument of Go type <code>string</code>.

During toolchain bootstrap, the environment variables <code>CC</code> and <code>CC_FOR_TARGET</code> specify

the default C compiler that the resulting toolchain will use for host and target builds, respectively.

However, if the toolchain will be used with multiple targets, it may be necessary to specify a different C compiler for each

(for example, a different compiler for <code>darwin/arm64</code> versus <code>linux/ppc64le</code>).

The new set of environment variables <code>CC_FOR_goos_goarch</code>

allows specifying a different default C compiler for each target.

Note that these variables only apply during toolchain bootstrap,

to set the defaults used by the resulting toolchain.

Later <code>go</code> <code>build</code> commands use the <code>CC</code> environment

variable or else the built-in default.

Cgo now translates some C types that would normally map to a pointer

type in Go, to a <code>uintptr</code> instead. These types include

the <code>CFTypeRef</code> hierarchy in Darwin's CoreFoundation

framework and the <code>jobject</code> hierarchy in Java's JNI

interface.

These types must be <code>uintptr</code> on the Go side because they

would otherwise confuse the Go garbage collector; they are sometimes

not really pointers but data structures encoded in a pointer-sized integer.

Pointers to Go memory must not be stored in these <code>uintptr</code> values.

Because of this change, values of the affected types need to be

zero-initialized with the constant <code>0</code> instead of the

constant <code>nil</code>. Go 1.10 provides <code>gofix</code>

modules to help with that rewrite:

<pre>

go tool fix -r cftype <pkg>

go tool fix -r jni <pkg>

</pre>

For more details, see the <a href="/cmd/cgo/">cgo documentation</a>.

The <code>go</code> <code>doc</code> tool now adds functions returning slices of <code>T</code> or <code>*T</code>

to the display of type <code>T</code>, similar to the existing behavior for functions returning single <code>T</code> or <code>*T</code> results.

For example:

<pre>

$ go doc mail.Address

package mail // import "net/mail"

type Address struct {

Name string

Address string

}

Address represents a single mail address.

func ParseAddress(address string) (*Address, error)

func ParseAddressList(list string) ([]*Address, error)

func (a *Address) String() string

</pre>

Previously, <code>ParseAddressList</code> was only shown in the package overview (<code>go</code> <code>doc</code> <code>mail</code>).

The <code>go</code> <code>fix</code> tool now replaces imports of <code>"golang.org/x/net/context"</code>

with <code>"context"</code>.

(Forwarding aliases in the former make it completely equivalent to the latter when using Go 1.9 or later.)

The <code>go</code> <code>get</code> command now supports Fossil source code repositories.

<h3 id="pprof">Pprof</h3>

The blocking and mutex profiles produced by the <code>runtime/pprof</code> package

now include symbol information, so they can be viewed

in <code>go</code> <code>tool</code> <code>pprof</code>

without the binary that produced the profile.

(All other profile types were changed to include symbol information in Go 1.9.)

The <a href="/cmd/pprof/"><code>go</code> <code>tool</code> <code>pprof</code></a>

profile visualizer has been updated to git version 9e20b5b (2017-11-08)

from <a href="https://github.com/google/pprof">github.com/google/pprof</a>,

which includes an updated web interface.

The <a href="/cmd/vet/"><code>go</code> <code>vet</code></a> command now always has access to

complete, up-to-date type information when checking packages, even for packages using cgo or vendored imports.

The reports should be more accurate as a result.

Note that only <code>go</code> <code>vet</code> has access to this information;

the more low-level <code>go</code> <code>tool</code> <code>vet</code> does not

and should be avoided except when working on <code>vet</code> itself.

(As of Go 1.9, <code>go</code> <code>vet</code> provides access to all the same flags as

<code>go</code> <code>tool</code> <code>vet</code>.)

<h3 id="diag">Diagnostics</h3>

This release includes a new <a href="/doc/diagnostics.html">overview of available Go program diagnostic tools</a>.

<h3 id="gofmt">Gofmt</h3>

Two minor details of the default formatting of Go source code have changed.

First, certain complex three-index slice expressions previously formatted like

<code>x[i+1</code> <code>:</code> <code>j:k]</code> and now

format with more consistent spacing: <code>x[i+1</code> <code>:</code> <code>j</code> <code>:</code> <code>k]</code>.

Second, single-method interface literals written on a single line,

which are sometimes used in type assertions,

are no longer split onto multiple lines.

Note that these kinds of minor updates to gofmt are expected from time to time.

In general, we recommend against building systems that check that source code

matches the output of a specific version of gofmt.

For example, a continuous integration test that fails if any code already checked into

a repository is not “properly formatted” is inherently fragile and not recommended.

If multiple programs must agree about which version of gofmt is used to format a source file,

we recommend that they do this by arranging to invoke the same gofmt binary.

For example, in the Go open source repository, our Git pre-commit hook is written in Go

and could import <code>go/format</code> directly, but instead it invokes the <code>gofmt</code>

binary found in the current path, so that the pre-commit hook need not be recompiled

each time <code>gofmt</code> changes.

<h3 id="compiler">Compiler Toolchain</h3>

The compiler includes many improvements to the performance of generated code,

spread fairly evenly across the supported architectures.

The DWARF debug information recorded in binaries has been improved in a few ways:

constant values are now recorded;

line number information is more accurate, making source-level stepping through a program work better;

and each package is now presented as its own DWARF compilation unit.

The various <a href="https://docs.google.com/document/d/1nr-TQHw_er6GOQRsF6T43GGhFDelrAP0NqSS_00RgZQ/edit">build modes</a>

have been ported to more systems.

Specifically, <code>c-shared</code> now works on <code>linux/ppc64le</code>, <code>windows/386</code>, and <code>windows/amd64</code>;

<code>pie</code> now works on <code>darwin/amd64</code> and also forces the use of external linking on all systems;

and <code>plugin</code> now works on <code>linux/ppc64le</code> and <code>darwin/amd64</code>.

The <code>linux/ppc64le</code> port now requires the use of external linking

with any programs that use cgo, even uses by the standard library.

<h3 id="asm">Assembler</h3>

For the ARM 32-bit port, the assembler now supports the instructions

<code>BFC</code>,

<code>BFI</code>,

<code>BFX</code>,

<code>BFXU</code>,

<code>FMULAD</code>,

<code>FMULAF</code>,

<code>FMULSD</code>,

<code>FMULSF</code>,

<code>FNMULAD</code>,

<code>FNMULAF</code>,

<code>FNMULSD</code>,

<code>FNMULSF</code>,

<code>MULAD</code>,

<code>MULAF</code>,

<code>MULSD</code>,

<code>MULSF</code>,

<code>NMULAD</code>,

<code>NMULAF</code>,

<code>NMULD</code>,

<code>NMULF</code>,

<code>NMULSD</code>,

<code>NMULSF</code>,

<code>XTAB</code>,

<code>XTABU</code>,

<code>XTAH</code>,

and

<code>XTAHU</code>.

For the ARM 64-bit port, the assembler now supports the

<code>VADD</code>,

<code>VADDP</code>,

<code>VADDV</code>,

<code>VAND</code>,

<code>VCMEQ</code>,

<code>VDUP</code>,

<code>VEOR</code>,

<code>VLD1</code>,

<code>VMOV</code>,

<code>VMOVI</code>,

<code>VMOVS</code>,

<code>VORR</code>,

<code>VREV32</code>,

and

instructions.

For the PowerPC 64-bit port, the assembler now supports the POWER9 instructions

<code>ADDEX</code>,

<code>CMPEQB</code>,

<code>COPY</code>,

<code>DARN</code>,

<code>LDMX</code>,

<code>MADDHD</code>,

<code>MADDHDU</code>,

<code>MADDLD</code>,

<code>MFVSRLD</code>,

<code>MTVSRDD</code>,

<code>MTVSRWS</code>,

<code>PASTECC</code>,

<code>VCMPNEZB</code>,

<code>VCMPNEZBCC</code>,

and

<code>VMSUMUDM</code>.

For the S390X port, the assembler now supports the

<code>TMHH</code>,

<code>TMHL</code>,

<code>TMLH</code>,

and

instructions.

For the X86 64-bit port, the assembler now supports 359 new instructions,

including the full AVX, AVX2, BMI, BMI2, F16C, FMA3, SSE2, SSE3, SSSE3, SSE4.1, and SSE4.2 extension sets.

The assembler also no longer implements <code>MOVL</code> <code>$0,</code> <code>AX</code>

as an <code>XORL</code> instruction,

to avoid clearing the condition flags unexpectedly.

<h3 id="gccgo">Gccgo</h3>

Due to the alignment of Go's semiannual release schedule with GCC's

annual release schedule,

GCC release 7 contains the Go 1.8.3 version of gccgo.

We expect that the next release, GCC 8, will contain the Go 1.10

version of gccgo.

<h2 id="runtime">Runtime</h2>

The behavior of nested calls to

<a href="/pkg/runtime/#LockOSThread"><code>LockOSThread</code></a> and

<a href="/pkg/runtime/#UnlockOSThread"><code>UnlockOSThread</code></a>

has changed.

These functions control whether a goroutine is locked to a specific operating system thread,

so that the goroutine only runs on that thread, and the thread only runs that goroutine.

Previously, calling <code>LockOSThread</code> more than once in a row

was equivalent to calling it once, and a single <code>UnlockOSThread</code>

always unlocked the thread.

Now, the calls nest: if <code>LockOSThread</code> is called multiple times,

<code>UnlockOSThread</code> must be called the same number of times

in order to unlock the thread.

Existing code that was careful not to nest these calls will remain correct.

Existing code that incorrectly assumed the calls nested will become correct.

Most uses of these functions in public Go source code falls into the second category.

Because one common use of <code>LockOSThread</code> and <code>UnlockOSThread</code>

is to allow Go code to reliably modify thread-local state (for example, Linux or Plan 9 name spaces),

the runtime now treats locked threads as unsuitable for reuse or for creating new threads.

Stack traces no longer include implicit wrapper functions (previously marked <code><autogenerated></code>),

unless a fault or panic happens in the wrapper itself.

As a result, skip counts passed to functions like <a href="/pkg/runtime/#Caller"><code>Caller</code></a>

should now always match the structure of the code as written, rather than depending on

optimization decisions and implementation details.

The garbage collector has been modified to reduce its impact on allocation latency.

It now uses a smaller fraction of the overall CPU when running, but it may run more of the time.

The total CPU consumed by the garbage collector has not changed significantly.

The <a href="/pkg/runtime/#GOROOT"><code>GOROOT</code></a> function

now defaults (when the <code>$GOROOT</code> environment variable is not set)

to the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect

at the time the calling program was compiled.

Previously it used the <code>GOROOT</code> or <code>GOROOT_FINAL</code> in effect

at the time the toolchain that compiled the calling program was compiled.

There is no longer a limit on the <a href="/pkg/runtime/#GOMAXPROCS"><code>GOMAXPROCS</code></a> setting.

(In Go 1.9 the limit was 1024.)

<h2 id="performance">Performance</h2>

As always, the changes are so general and varied that precise

statements about performance are difficult to make. Most programs

should run a bit faster, due to speedups in the garbage collector,

better generated code, and optimizations in the core library.

<h2 id="gc">Garbage Collector</h2>

Many applications should experience significantly lower allocation latency and overall performance overhead when the garbage collector is active.

<h2 id="library">Core library</h2>

All of the changes to the standard library are minor.

The changes in <a href="#bytes">bytes</a>

and <a href="#net/url">net/url</a> are the most likely to require updating of existing programs.

<h3 id="minor_library_changes">Minor changes to the library</h3>

As always, there are various minor changes and updates to the library,

made with the Go 1 <a href="/doc/go1compat">promise of compatibility</a>

in mind.

<dl id="archive/tar"><dt><a href="/pkg/archive/tar/">archive/tar</a></dt>

<dd>

In general, the handling of special header formats is significantly improved and expanded.

<a href="/pkg/archive/tar/#FileInfoHeader"><code>FileInfoHeader</code></a> has always

recorded the Unix UID and GID numbers from its <a href="/pkg/os/#FileInfo"><code>os.FileInfo</code></a> argument

(specifically, from the system-dependent information returned by the <code>FileInfo</code>'s <code>Sys</code> method)

in the returned <a href="/pkg/archive/tar/#Header"><code>Header</code></a>.

Now it also records the user and group names corresponding to those IDs,

as well as the major and minor device numbers for device files.

The new <a href="/pkg/archive/tar/#Header"><code>Header.Format</code></a> field

of type <a href="/pkg/archive/tar/#Format"><code>Format</code></a>

controls which tar header format the <a href="/pkg/archive/tar/#Writer"><code>Writer</code></a> uses.

The default, as before, is to select the most widely-supported header type

that can encode the fields needed by the header (USTAR if possible, or else PAX if possible, or else GNU).

The <a href="/pkg/archive/tar/#Reader"><code>Reader</code></a> sets <code>Header.Format</code> for each header it reads.

<code>Reader</code> and the <code>Writer</code> now support arbitrary PAX records,

using the new <a href="/pkg/archive/tar/#Header"><code>Header.PAXRecords</code></a> field,

a generalization of the existing <code>Xattrs</code> field.

The <code>Reader</code> no longer insists that the file name or link name in GNU headers

be valid UTF-8.

When writing PAX- or GNU-format headers, the <code>Writer</code> now includes

the <code>Header.AccessTime</code> and <code>Header.ChangeTime</code> fields (if set).

When writing PAX-format headers, the times include sub-second precision.

</dl>

<dl id="archive/zip"><dt><a href="/pkg/archive/zip/">archive/zip</a></dt>

<dd>

Go 1.10 adds more complete support for times and character set encodings in ZIP archives.

The original ZIP format used the standard MS-DOS encoding of year, month, day, hour, minute, and second into fields in two 16-bit values.

That encoding cannot represent time zones or odd seconds, so multiple extensions have been

introduced to allow richer encodings.

In Go 1.10, the <a href="/pkg/archive/zip/#Reader"><code>Reader</code></a> and <a href="/pkg/archive/zip/#Writer"><code>Writer</code></a>

now support the widely-understood Info-Zip extension that encodes the time separately in the 32-bit Unix “seconds since epoch” form.

The <a href="/pkg/archive/zip/#FileHeader"><code>FileHeader</code></a>'s new <code>Modified</code> field of type <a href="/pkg/time/#Time"><code>time.Time</code></a>

obsoletes the <code>ModifiedTime</code> and <code>ModifiedDate</code> fields, which continue to hold the MS-DOS encoding.

The <code>Reader</code> and <code>Writer</code> now adopt the common

convention that a ZIP archive storing a time zone-independent Unix time

also stores the local time in the MS-DOS field,

so that the time zone offset can be inferred.

For compatibility, the <a href="/pkg/archive/zip/#FileHeader.ModTime"><code>ModTime</code></a> and

<a href="/pkg/archive/zip/#FileHeader.SetModTime"><code>SetModTime</code></a> methods

behave the same as in earlier releases; new code should use <code>Modified</code> directly.

The header for each file in a ZIP archive has a flag bit indicating whether

the name and comment fields are encoded as UTF-8, as opposed to a system-specific default encoding.

In Go 1.8 and earlier, the <code>Writer</code> never set the UTF-8 bit.

In Go 1.9, the <code>Writer</code> changed to set the UTF-8 bit almost always.

This broke the creation of ZIP archives containing Shift-JIS file names.

In Go 1.10, the <code>Writer</code> now sets the UTF-8 bit only when

both the name and the comment field are valid UTF-8 and at least one is non-ASCII.

Because non-ASCII encodings very rarely look like valid UTF-8, the new

heuristic should be correct nearly all the time.

Setting a <code>FileHeader</code>'s new <code>NonUTF8</code> field to true

disables the heuristic entirely for that file.

The <code>Writer</code> also now supports setting the end-of-central-directory record's comment field,

by calling the <code>Writer</code>'s new <a href="/pkg/archive/zip/#Writer.SetComment"><code>SetComment</code></a> method.

</dl>

<dl id="bufio"><dt><a href="/pkg/bufio/">bufio</a></dt>

<dd>

The new <a href="/pkg/bufio/#Reader.Size"><code>Reader.Size</code></a>

and <a href="/pkg/bufio/#Writer.Size"><code>Writer.Size</code></a>

methods report the <code>Reader</code> or <code>Writer</code>'s underlying buffer size.

</dl>

<dl id="bytes"><dt><a href="/pkg/bytes/">bytes</a></dt>

<dd>

The

<a href="/pkg/bytes/#Fields"><code>Fields</code></a>,

<a href="/pkg/bytes/#FieldsFunc"><code>FieldsFunc</code></a>,

<a href="/pkg/bytes/#Split"><code>Split</code></a>,

and

<a href="/pkg/bytes/#SplitAfter"><code>SplitAfter</code></a>

functions have always returned subslices of their inputs.

Go 1.10 changes each returned subslice to have capacity equal to its length,

so that appending to one cannot overwrite adjacent data in the original input.

</dl>

<dl id="crypto/cipher"><dt><a href="/pkg/crypto/cipher/">crypto/cipher</a></dt>

<dd>

<a href="/pkg/crypto/cipher/#NewOFB"><code>NewOFB</code></a> now panics if given

an initialization vector of incorrect length, like the other constructors in the

package always have.

(Previously it returned a nil <code>Stream</code> implementation.)

</dl>

<dl id="crypto/tls"><dt><a href="/pkg/crypto/tls/">crypto/tls</a></dt>

<dd>

The TLS server now advertises support for SHA-512 signatures when using TLS 1.2.

The server already supported the signatures, but some clients would not select

them unless explicitly advertised.

</dl>

<dl id="crypto/x509"><dt><a href="/pkg/crypto/x509/">crypto/x509</a></dt>

<dd>

<a href="/pkg/crypto/x509/#Certificate.Verify"><code>Certificate.Verify</code></a>

now enforces the name constraints for all

names contained in the certificate, not just the one name that a client has asked about.

Extended key usage restrictions are similarly now checked all at once.

As a result, after a certificate has been validated, now it can be trusted in its entirety.

It is no longer necessary to revalidate the certificate for each additional name

or key usage.

Parsed certificates also now report URI names and IP, email, and URI constraints, using the new

<a href="/pkg/crypto/x509/#Certificate"><code>Certificate</code></a> fields

<code>URIs</code>, <code>PermittedIPRanges</code>, <code>ExcludedIPRanges</code>,

<code>PermittedEmailAddresses</code>, <code>ExcludedEmailAddresses</code>,

<code>PermittedURIDomains</code>, and <code>ExcludedURIDomains</code>. Certificates with

invalid values for those fields are now rejected.

The new <a href="/pkg/crypto/x509/#MarshalPKCS1PublicKey"><code>MarshalPKCS1PublicKey</code></a>

and <a href="/pkg/crypto/x509/#ParsePKCS1PublicKey"><code>ParsePKCS1PublicKey</code></a>

functions convert an RSA public key to and from PKCS#1-encoded form.

The new <a href="/pkg/crypto/x509/#MarshalPKCS8PrivateKey"><code>MarshalPKCS8PrivateKey</code></a>

function converts a private key to PKCS#8-encoded form.

(<a href="/pkg/crypto/x509/#ParsePKCS8PrivateKey"><code>ParsePKCS8PrivateKey</code></a>

has existed since Go 1.)

</dl>

<dl id="crypto/x509/pkix"><dt><a href="/pkg/crypto/x509/pkix/">crypto/x509/pkix</a></dt>

<dd>

<a href="/pkg/crypto/x509/pkix/#Name"><code>Name</code></a> now implements a

<a href="/pkg/crypto/x509/pkix/#Name.String"><code>String</code></a> method that

formats the X.509 distinguished name in the standard RFC 2253 format.

</dl>

<dl id="database/sql/driver"><dt><a href="/pkg/database/sql/driver/">database/sql/driver</a></dt>

<dd>

Drivers that currently hold on to the destination buffer provided by

<a href="/pkg/database/sql/driver/#Rows.Next"><code>driver.Rows.Next</code></a> should ensure they no longer

write to a buffer assigned to the destination array outside of that call.

Drivers must be careful that underlying buffers are not modified when closing

<a href="/pkg/database/sql/driver/#Rows"><code>driver.Rows</code></a>.

Drivers that want to construct a <a href="/pkg/database/sql/#DB"><code>sql.DB</code></a> for

their clients can now implement the <a href="/pkg/database/sql/driver/#Connector"><code>Connector</code></a> interface

and call the new <a href="/pkg/database/sql/#OpenDB"><code>sql.OpenDB</code></a> function,

instead of needing to encode all configuration into a string

passed to <a href="/pkg/database/sql/#Open"><code>sql.Open</code></a>.

Drivers that want to parse the configuration string only once per <code>sql.DB</code>

instead of once per <a href="/pkg/database/sql/#Conn"><code>sql.Conn</code></a>,

or that want access to each <code>sql.Conn</code>'s underlying context,

can make their <a href="/pkg/database/sql/driver/#Driver"><code>Driver</code></a>

implementations also implement <a href="/pkg/database/sql/driver/#DriverContext"><code>DriverContext</code></a>'s

new <code>OpenConnector</code> method.

Drivers that implement <a href="/pkg/database/sql/driver/#ExecerContext"><code>ExecerContext</code></a>

no longer need to implement <a href="/pkg/database/sql/driver/#Execer"><code>Execer</code></a>;

similarly, drivers that implement <a href="/pkg/database/sql/driver/#QueryerContext"><code>QueryerContext</code></a>

no longer need to implement <a href="/pkg/database/sql/driver/#Queryer"><code>Queryer</code></a>.

Previously, even if the context-based interfaces were implemented they were ignored

unless the non-context-based interfaces were also implemented.

To allow drivers to better isolate different clients using a cached driver connection in succession,

if a <a href="/pkg/database/sql/driver/#Conn"><code>Conn</code></a> implements the new

<a href="/pkg/database/sql/driver/#SessionResetter"><code>SessionResetter</code></a> interface,

<code>database/sql</code> will now call <code>ResetSession</code> before

reusing the <code>Conn</code> for a new client.

</dl>

<dl id="debug/elf"><dt><a href="/pkg/debug/elf/">debug/elf</a></dt>

<dd>

This release adds 348 new relocation constants divided between the relocation types

<a href="/pkg/debug/elf/#R_386"><code>R_386</code></a>,

<a href="/pkg/debug/elf/#R_AARCH64"><code>R_AARCH64</code></a>,

<a href="/pkg/debug/elf/#R_ARM"><code>R_ARM</code></a>,

<a href="/pkg/debug/elf/#R_PPC64"><code>R_PPC64</code></a>,

and

<a href="/pkg/debug/elf/#R_X86_64"><code>R_X86_64</code></a>.

</dl>

<dl id="debug/macho"><dt><a href="/pkg/debug/macho/">debug/macho</a></dt>

<dd>

Go 1.10 adds support for reading relocations from Mach-O sections,

using the <a href="/pkg/debug/macho#Section"><code>Section</code></a> struct's new <code>Relocs</code> field

and the new <a href="/pkg/debug/macho/#Reloc"><code>Reloc</code></a>,

<a href="/pkg/debug/macho/#RelocTypeARM"><code>RelocTypeARM</code></a>,

<a href="/pkg/debug/macho/#RelocTypeARM64"><code>RelocTypeARM64</code></a>,

<a href="/pkg/debug/macho/#RelocTypeGeneric"><code>RelocTypeGeneric</code></a>,

and

<a href="/pkg/debug/macho/#RelocTypeX86_64"><code>RelocTypeX86_64</code></a>

types and associated constants.

Go 1.10 also adds support for the <code>LC_RPATH</code> load command,

represented by the types

<a href="/pkg/debug/macho/#RpathCmd"><code>RpathCmd</code></a> and

<a href="/pkg/debug/macho/#Rpath"><code>Rpath</code></a>,

and new <a href="/pkg/debug/macho/#pkg-constants">named constants</a>

for the various flag bits found in headers.

</dl>

<dl id="encoding/asn1"><dt><a href="/pkg/encoding/asn1/">encoding/asn1</a></dt>

<dd>

<a href="/pkg/encoding/asn1/#Marshal"><code>Marshal</code></a> now correctly encodes

strings containing asterisks as type UTF8String instead of PrintableString,

unless the string is in a struct field with a tag forcing the use of PrintableString.

<code>Marshal</code> also now respects struct tags containing <code>application</code> directives.

The new <a href="/pkg/encoding/asn1/#MarshalWithParams"><code>MarshalWithParams</code></a>

function marshals its argument as if the additional params were its associated

struct field tag.

<a href="/pkg/encoding/asn1/#Unmarshal"><code>Unmarshal</code></a> now respects

struct field tags using the <code>explicit</code> and <code>tag</code>

directives.

Both <code>Marshal</code> and <code>Unmarshal</code> now support a new struct field tag

<code>numeric</code>, indicating an ASN.1 NumericString.

</dl>

<dl id="encoding/csv"><dt><a href="/pkg/encoding/csv/">encoding/csv</a></dt>

<dd>

<a href="/pkg/encoding/csv/#Reader"><code>Reader</code></a> now disallows the use of

nonsensical <code>Comma</code> and <code>Comment</code> settings,

such as NUL, carriage return, newline, invalid runes, and the Unicode replacement character,

or setting <code>Comma</code> and <code>Comment</code> equal to each other.

In the case of a syntax error in a CSV record that spans multiple input lines, <code>Reader</code>

now reports the line on which the record started in the <a href="/pkg/encoding/csv/#ParseError"><code>ParseError</code></a>'s new <code>StartLine</code> field.

</dl>

<dl id="encoding/hex"><dt><a href="/pkg/encoding/hex/">encoding/hex</a></dt>

<dd>

The new functions

<a href="/pkg/encoding/hex/#NewEncoder"><code>NewEncoder</code></a>

and

<a href="/pkg/encoding/hex/#NewDecoder"><code>NewDecoder</code></a>

provide streaming conversions to and from hexadecimal,

analogous to equivalent functions already in

<a href="/pkg/encoding/base32/">encoding/base32</a>

and

<a href="/pkg/encoding/base64/">encoding/base64</a>.

When the functions

<a href="/pkg/encoding/hex/#Decode"><code>Decode</code></a>

and

<a href="/pkg/encoding/hex/#DecodeString"><code>DecodeString</code></a>

encounter malformed input,

they now return the number of bytes already converted

along with the error.

Previously they always returned a count of 0 with any error.

</dl>

<dl id="encoding/json"><dt><a href="/pkg/encoding/json/">encoding/json</a></dt>

<dd>

The <a href="/pkg/encoding/json/#Decoder"><code>Decoder</code></a>

adds a new method

<a href="/pkg/encoding/json/#Decoder.DisallowUnknownFields"><code>DisallowUnknownFields</code></a>

that causes it to report inputs with unknown JSON fields as a decoding error.

(The default behavior has always been to discard unknown fields.)

As a result of <a href="#reflect">fixing a reflect bug</a>,

<a href="/pkg/encoding/json/#Unmarshal"><code>Unmarshal</code></a>

can no longer decode into fields inside

embedded pointers to unexported struct types,

because it cannot initialize the unexported embedded pointer

to point at fresh storage.

<code>Unmarshal</code> now returns an error in this case.

</dl>

<dl id="encoding/pem"><dt><a href="/pkg/encoding/pem/">encoding/pem</a></dt>

<dd>

<a href="/pkg/encoding/pem/#Encode"><code>Encode</code></a>

and

<a href="/pkg/encoding/pem/#EncodeToMemory"><code>EncodeToMemory</code></a>

no longer generate partial output when presented with a

block that is impossible to encode as PEM data.

</dl>

<dl id="encoding/xml"><dt><a href="/pkg/encoding/xml/">encoding/xml</a></dt>

<dd>

View remainder of file in raw view

FilesExpand file tree

go1.10.html

Latest commit

History

go1.10.html

File metadata and controls