Apple API

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package apns provide a Apple Push Notification service provider. Apple Push Notification service (APNs) is the centerpiece of the remote notifications feature. It is a robust and highly efficient service for propagating information to iOS (and, indirectly, watchOS), tvOS, and macOS devices. On initial activation, a device establishes an accredited and encrypted IP connection with APNs and receives notifications over this persistent connection. If a notification for an app arrives when that app is not running, the device alerts the user that the app has data waiting for it. You provide your own server to generate remote notifications for the users of your app. This server, known as the provider, has three main responsibilities. It: For each notification, the provider: On receiving the HTTP/2 request, APNs delivers the notification payload to your app on the user's device. Apple Push Notification service includes a default Quality of Service (QoS) component that performs a store-and-forward function. If APNs attempts to deliver a notification but the destination device is offline, APNs stores the notification for a limited period of time and delivers it to the device when the device becomes available. This mechanism stores only one recent notification per device, per app: if you send multiple notifications while a device is offline, a new notification causes the previous notification to be discarded. If a device remains offline for a long time, all notifications that were being stored for it are discarded; when the device goes back online, none of the notifications are displayed. When a device is online, all the notifications you send are delivered and available to the user. However, you can avoid showing duplicate notifications by employing a collapse identifier across multiple, identical notifications. The APNs request header key for the collapse identifier is "apns-collapse-id". For example, a news service that sends the same headline twice in a row could employ the same collapse identifier for both push notification requests. APNs would then take care of coalescing these requests into a single notification for delivery to a device. To ensure secure communication, APNs servers employ connection certificates, certification authority (CA) certificates, and cryptographic keys (private and public) to validate connections to, and identities of, providers and devices. APNs regulates the entry points between providers and devices using two levels of trust: connection trust and device token trust. Connection trust establishes certainty that APNs is connected to an authorized provider, owned by a company that Apple has agreed to deliver notifications for. You must take steps to ensure connection trust exists between your provider servers and APNs. APNs also uses connection trust with each device to ensure the legitimacy of the device. Connection trust with the device is handled automatically by APNs. Device token trust ensures that notifications are routed only between legitimate start and end points. A device token is an opaque, unique identifier assigned to a specific app on a specific device. Each app instance receives its unique token when it registers with APNs. The app must share this token with its provider, to allow the provider to employ the token when communicating with APNs. Each notification that your provider sends to APNs must include the device token, which ensures that the notification is delivered only to the app-device combination for which it is intended. Important: To protect user privacy, do not attempt to use a device token to identify a device. Device tokens can change after updating the operating system, and always change when a device's data and settings are erased. Whenever the system delivers a device token to an instance of your app, the app must forward it to your provider servers to allow further push notifications to the device. A provider using the HTTP/2-based APNs Provider API can use JSON web tokens (JWT) to validate the provider's connection with APNs. In this scheme, the provider does not require a certificate-plus-private key to establish connection. Instead, you provision a public key to be retained by Apple, and a private key which you retain and protect. Your providers then use your private key to generate and sign JWT authentication tokens. Each of your push requests must include an authentication token. Important: To establish TLS sessions with APNs, you must ensure that a GeoTrust Global CA root certificate is installed on each of your providers. You can download this certificate from the GeoTrust Root Certificates website: https://www.geotrust.com/resources/root-certificates/. The HTTP/2-based provider connection is valid for delivery to one specific app, identified by the topic (the app bundle ID) specified in the certificate. Depending on how you configure and provision your APNs Transport Layer Security (TLS) certificate, the trusted connection can also be valid for delivery of remote notifications to other items associated with your app, including Apple Watch complications and voice-over-Internet Protocol (VoIP) services. APNs delivers these notifications even when those items are running in the background. APNs maintains a certificate revocation list; if a provider's certificate is on the revocation list, APNs can revoke provider trust (that is, APNs can refuse the TLS initiation connection).

Package dnssd implements a wrapper for Apple's C DNS Service Discovery API. The DNS Service Discovery API is part of the Apple Bonjour zero configuration networking stack. The API allows for network services to be registered, browsed and resolved without configuration via multicast DNS in the ".local" domain and with additional configuration in unicast DNS domains. A service consists of a name, type, host, port and a set of key-value pairs containing meta information. Bonjour is bundled with OS X and available for Windows via Bonjour Print Services for Windows¹, the Bonjour SDK for Windows² or bundled with iTunes. For other POSIX platforms Apple offer mDNSResponder³ as open-source, however the Avahi⁴ project is the de facto choice on most Linux and BSD systems. Although Avahi has a different API, it does offer a compatibility shim which covers a subset of the DNS Service Discovery API, and which this package largely sticks to. The DNS Service Discovery API is wrapped as follows: All operations require a callback be set. RegisterOp, BrowseOp and ResolveOp require a service type be set. QueryOp requires name, class and type be set. If an InterfaceIndex is not set the default value of InterfaceIndexAny is used which applies the operation to all network interfaces. For operations that take a domain, if no domain is set or the domain is set to an empty string the operation applies to all applicable DNS-SD domains. If a service is registered with an empty string as it's name, the local computer name (or hostname) will be substitued. If no host is specified a hostname for the local machine will be used. By default services will be renamed with a numeric suffix if a name collision occurs. Callbacks are executed in serial. If an error is supplied to a callback the operation will no longer be active and other arguments must be ignored.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package mtl provides access to Apple's Metal API (https://developer.apple.com/documentation/metal). Package mtl requires macOS version 10.13 or newer. This package is in very early stages of development. The API will change when opportunities for improvement are discovered; it is not yet frozen. Less than 20% of the Metal API surface is implemented. Current functionality is sufficient to render very basic geometry.

Package id3 implements a decoder and encoder for ID3 tags. ID3 uses nomenclature that might be counterintuitive to people not familiar with it. Because this library uses the same choice of words the following list of clarifications is included. This library supports reading v2.3 and v2.4 tags, but only writing v2.4 tags. The primary reason for not allowing writing older versions is that they cannot represent all data that is available with v2.4, and designing the API in a way that's both user friendly and able to reject data is not worth the trouble. The library's internal representation of tags matches that of v2.4. When tags with an older version are being read, they will be automatically converted to v2.4. One consequence of this is that when you read a file with v2.3 tags and immediately save it, it will now be a file with valid v2.4 tags. The upgrade process makes the following changes to the tags: One special case is the TRDA frame because there is no way to automatically convert it to v2.4. The upgrade process will not directly delete the frame, so that you can manually upgrade it if desired, but it won't be written back to the file. The frame is rarely used and insignificant, so it's not a big loss. There are two ways to access frames: Using provided getter and setter methods (there is one for every standard frame), and working directly with the underlying frames. For frames that usually support multiple values, e.g. languages, there will be two different setters and getters: One that operates on slices and one that operates on single values. When getting a single value, it will return the first value from the underlying list. When setting a single value, it will overwrite the list with a single value. Text frames and user text frames can be manipulated with the GetTextFrame* and SetTextFrame* class of functions. There are special methods for working with integers, slices and times. This class of functions expects the raw frame names (e.g. "TLEN"), with the special case of user text frames ("TXXX") where it expects a format of the kind "TXXX:The frame description" to address a specific user text frame. While ID3v2 allows a variety of encodings (ISO-8859-1, UTF-16 and in v2.4 also UTF-8), this library only supports writing UTF-8. When reading frames with different encodings, they will be converted to UTF-8. The rationale behind this is that UTF-8 is the encoding assumed by most of the Go standard library, and that the other encodings have no realistic benefits over UTF-8. There are two kinds of invalid data that can be encountered: Data that doesn't look like a valid frame, and data that is invalid in the context of its frame. An example for the first case is a frame identifier that doesn't consist of only A-Z0-9. That usually happens when other programs wrote invalid data. One common case are wrongly encoded sizes, which will cause us to read random binary data. An example for the second case is text that isn't valid according to the specified encoding. In the first case, parsing of the entire tag will be aborted because it cannot be ensured that bad things won't happen. In the second case only that specific frame will be dropped. Unsupported frames, like extensions by Apple, will be left untouched, meaning that they will be read and written as raw byte slices. If you know how to handle them, you can write your own function to parse and modify the content. All unsupported frames will be of type UnsupportedFrame.

Package dnssd implements a wrapper for Apple's C DNS Service Discovery API. The DNS Service Discovery API is part of the Apple Bonjour zero configuration networking stack. The API allows for network services to be registered, browsed and resolved without configuration via multicast DNS in the ".local" domain and with additional configuration in unicast DNS domains. A service consists of a name, type, host, port and a set of key-value pairs containing meta information. Bonjour is bundled with OS X and available for Windows via Bonjour Print Services for Windows¹, the Bonjour SDK for Windows² or bundled with iTunes. For other POSIX platforms Apple offer mDNSResponder³ as open-source, however the Avahi⁴ project is the de facto choice on most Linux and BSD systems. Although Avahi has a different API, it does offer a compatibility shim which covers a subset of the DNS Service Discovery API, and which this package largely sticks to. The DNS Service Discovery API is wrapped as follows: All operations require a callback be set. RegisterOp, BrowseOp and ResolveOp require a service type be set. QueryOp requires name, class and type be set. If an InterfaceIndex is not set the default value of InterfaceIndexAny is used which applies the operation to all network interfaces. For operations that take a domain, if no domain is set or the domain is set to an empty string the operation applies to all applicable DNS-SD domains. If a service is registered with an empty string as it's name, the local computer name (or hostname) will be substitued. If no host is specified a hostname for the local machine will be used. By default services will be renamed with a numeric suffix if a name collision occurs. Callbacks are executed in serial. If an error is supplied to a callback the operation will no longer be active and other arguments must be ignored.

Package plist provides an API for reading Apple property lists.

Package dnssd implements a wrapper for Apple's C DNS Service Discovery API. The DNS Service Discovery API is part of the Apple Bonjour zero configuration networking stack. The API allows for network services to be registered, browsed and resolved without configuration via multicast DNS in the ".local" domain and with additional configuration in unicast DNS domains. A service consists of a name, type, host, port and a set of key-value pairs containing meta information. Bonjour is bundled with OS X and available for Windows via Bonjour Print Services for Windows¹, the Bonjour SDK for Windows² or bundled with iTunes. For other POSIX platforms Apple offer mDNSResponder³ as open-source, however the Avahi⁴ project is the de facto choice on most Linux and BSD systems. Although Avahi has a different API, it does offer a compatibility shim which covers a subset of the DNS Service Discovery API, and which this package largely sticks to. The DNS Service Discovery API is wrapped as follows: All operations require a callback be set. RegisterOp, BrowseOp and ResolveOp require a service type be set. QueryOp requires name, class and type be set. If an InterfaceIndex is not set the default value of InterfaceIndexAny is used which applies the operation to all network interfaces. For operations that take a domain, if no domain is set or the domain is set to an empty string the operation applies to all applicable DNS-SD domains. If a service is registered with an empty string as it's name, the local computer name (or hostname) will be substitued. If no host is specified a hostname for the local machine will be used. By default services will be renamed with a numeric suffix if a name collision occurs. Callbacks are executed in serial. If an error is supplied to a callback the operation will no longer be active and other arguments must be ignored.

Package mapper makes it easy to "pass" Go values by way of an opaque pointer into C code via cgo, without violating the cgo pointer passing rules, outlined at https://golang.org/cmd/cgo/#hdr-Passing_pointers. When that external code calls back into Go via a callback, you can use the passed opaque pointer to retrieve the Go value again. Our `Mapper` does this by associating an opaque `Key` with the Go object, and having the caller pass the key's handle to the C code. Later, in a Go callback, the Go object can be obtained using the `Get` method on the `Mapper` in exchange for the opaque pointer (key). You can create a `Mapper` object for each different category of mapping, or reuse the same one for all, with the caveats of mapping limits described below. A global mapper, `G` is provided for your convenience. Internally, the mapper uses a RWLock-protected Go map to associate `Keys` with Go values. The following patterns are supported. You have a pointer already obtained from cgo, which is at least 2-bytes aligned. (Any pointer returned from malloc satisfies this property.) That pointer can be mapped to a Go value using the `MapPtrPair` method. The returned `Key` can then be used to obtain the mapped Go value using the `Get` method. You need to create a new mapping for a Go object, without having a pointer previously obtained from cgo. This might be the case with a C API that accepts an opaque "user defined" pointer (or "refCon" in Apple's APIs), but doesn't return its object until after the call. Such a user pointer might be passed to a callback that makes it way back to Go, where you then exchange the pointer for the mapped Go object. In this case, you can map a Go object to a unique `Key` that is returned from the `MapValue` method. To keep the implementation simple, the number of unique keys is limited to `sizeof(uintptr)/2`. When the limit is reached, the `MapValue` call panics. On a 64-bit system, it is unlikely that any long-running program will reach that limit. Under this pattern, you can "stretch" the map limit further on a 32-bit system by using multiple `Mapper`s, each for different categories of object mappings, instead of the global map `G`. Go 1.17 introduced a new Handle type that is similar to the functionality provided here; see https://pkg.go.dev/runtime/cgo@master#Handle. The main difference between this package and the new runtime/cgo Handle is that this package allows you to use an existing C pointer for the mapping, which turns out to be available quite often.

Package metal is a library for running computational tasks (GPGPU) on Apple silicon through Apple's Metal API. Apple's Metal API is a unified framework for performing various types of task on Apple silicon GPUs. It offers low-level, direct, detailed access to the hardware (hence, "metal" ) for fast and efficient processing. The processing centers around pipelines, which consist of a function to run and an arbitrary number of arguments and buffers. The metal function is parsed into a series of operations, and the arguments and buffers of data are streamed through it in SIMD groups. (For more details on SIMD groups and best practices for writing metal functions using them, see Apple's documentation on threads and threadgroups.) This library leverages Apple's Metal API to run computational processes in a distributed, parallel method. First, a metal function is parsed, added to a pipeline, and cached. This happens once for every metal function. Then, any number of metal buffers are created. A metal buffer is an array of arbitrary length that references items of an arbitrary type. The actual type is defined in the metal function's definition. Finally, the metal function is run with the metal buffers and any static arguments. This streams the arguments and the data in the buffers through the computational operation(s) as sequenced in the metal function. This is the mapping of Go types to Metal types: These are some helpful resources for understanding this process better and how to use the metal API efficiently: Details on the language specifications for writing metal functions can be found in the MSL Specification.

Package dnssd implements a wrapper for Apple's C DNS Service Discovery API. The DNS Service Discovery API is part of the Apple Bonjour zero configuration networking stack. The API allows for network services to be registered, browsed and resolved without configuration via multicast DNS in the ".local" domain and with additional configuration in unicast DNS domains. A service consists of a name, type, host, port and a set of key-value pairs containing meta information. Bonjour is bundled with OS X and available for Windows via Bonjour Print Services for Windows¹, the Bonjour SDK for Windows² or bundled with iTunes. For other POSIX platforms Apple offer mDNSResponder³ as open-source, however the Avahi⁴ project is the de facto choice on most Linux and BSD systems. Although Avahi has a different API, it does offer a compatibility shim which covers a subset of the DNS Service Discovery API, and which this package largely sticks to. The DNS Service Discovery API is wrapped as follows: All operations require a callback be set. RegisterOp, BrowseOp and ResolveOp require a service type be set. QueryOp requires name, class and type be set. If an InterfaceIndex is not set the default value of InterfaceIndexAny is used which applies the operation to all network interfaces. For operations that take a domain, if no domain is set or the domain is set to an empty string the operation applies to all applicable DNS-SD domains. If a service is registered with an empty string as it's name, the local computer name (or hostname) will be substitued. If no host is specified a hostname for the local machine will be used. By default services will be renamed with a numeric suffix if a name collision occurs. Callbacks are executed in serial. If an error is supplied to a callback the operation will no longer be active and other arguments must be ignored.

Package metal is a library for running computational tasks (GPGPU) on Apple silicon through Apple's Metal API. Apple's Metal API is a unified framework for performing various types of task on Apple silicon GPUs. It offers low-level, direct, detailed access to the hardware (hence, _metal_) for fast and efficient processing. The processing centers around pipelines, which consist of a function to run and an arbitrary number of buffers. The metal function is parsed into a series of operations, and the buffers of data are streamed through it in SIMD groups. (For more details on SIMD groups and best practices for writing metal functions using them, see Apple's documentation on threads and threadgroups.) This library leverages the Metal API to run computational processes in a distributed, parallel method. First, a metal function is parsed, added to a pipeline, and cached. This happens once for every metal function. Then, any number of metal buffers are created. A metal buffer is an array of arbitrary length that references items of an arbitrary type. The actual type is defined in the metal function's definition. Finally, the metal function is run with the metal buffers. This streams the data in the buffers through the computational operation(s) as sequenced in the metal function. This is the mapping of Go types to Metal types: These are some helpful resources for understanding this process better and how to use the metal API efficiently: Details on the language specifications for writing metal functions can be found in the MSL Specification.