Skip to content

Latest commit

 

History

History
303 lines (228 loc) · 9.4 KB

Manual.md

File metadata and controls

303 lines (228 loc) · 9.4 KB
Raw

Documentation Manual

This is the documentation manual for SwiftyZeroMQ. You will find useful documentation and examples in the sections below.

Installation

Manual project inclusion

  • Download framework source code from here
  • Drag the project into your project.
  • In your target's settings, please click on the + button under the Embedded Binaries section and add SwiftyZeroMQ.framework. In case it does not show up in the list, please close and reopen the project in Xcode.
  • Add import SwiftyZeroMQ in your code to test it.
  • Happy hacking :)

CocoaPods

CocoaPods is a package manager that manages dependencies for your Xcode projects.

Example

If you would like to try out the example iOS project, simply type:

$ pod try SwiftyZeroMQ

Steps

Please follow these steps to add SwiftyZeroMQ to your project:

  • Add the following lines to your Podfile:
use_frameworks!
pod 'SwiftyZeroMQ', '~> 1.0'
  • Run the following command in the project root directory:
$ pod install
  • Open the project in Xcode with the following command:
$ open YourProject.xcworkspace

Carthage

Carthage is a simple, decentralized dependency manager for Cocoa. Please follow these steps:

  • Add the following lines to your 'Cartfile':
github "azawawi/SwiftyZeroMQ" ~> 1.0
  • Build the SwiftyZeroMQ.framework with the following commands:
$ carthage bootstrap --platform iOS  # Build only the iOS platform
$ carthage bootstrap                 # Build all supported platforms (can be slow)

  • Open your Xcode project (if not open already)

  • In your target's settings, please click on the + button under the Embedded Binaries section and add Carthage/Build/iOS/SwiftyZeroMQ.framework

Swift Package Manager

Apple's Swift Package Manager (also known as SPM or SwiftPM) is a tool for managing the distribution of Swift code. It is integrated with the Swift build system to automate the process of downloading, compiling, and linking dependencies.

At the time of this writing (October 2016-2017), iOS is not supported. Pull requests are more than welcome once the iOS support lands in a future version.

Testing

  • In Xcode, open the project and type ⌘U to test it.

OR

  • In the terminal, please make sure that you have xcpretty and then run:
$ gem install xcpretty # Needs to be installed once for prettier output
$ ./run-tests.rb       # Runs framework unit tests on selected iOS versions

Bundled ZeroMQ library

The bundled universal static library for ZeroMQ 4.2.1 is provided in the Libraries folder. Please check the table shown below for included architectures and minimum platform version. Bitcode is enabled for all platforms except macOS.

Library Minimum OS version CPU Architectures
libzmq-ios.a 9.0 armv7 (iPhone 3GS till iPhone 4S), armv7s (iPhone 5 till iPhone 5c), arm64 (iPhone 5s and later), i386 and x86_64 (simulator)
libzmq-macos.a 10.11 x86_64
libzmq-tvos.a 9.0 arm64 (Apple TV 4), x86_64 (simulator)
libzmq-watchos.a 2.0 armv7k (Apple Watch), i386 (simulator)

Import

To import this module, please type:

import SwiftyZeroMQ

Low-level API

Low-level API is available once you import this module, ZeroMQ C++ API is usually prefixed by zmq_. For example, to print library version, please type:

var major: Int32 = 0
var minor: Int32 = 0
var patch: Int32 = 0
zmq_version(&major, &minor, &patch)
print("ZeroMQ library version is \(major).\(minor).\(patch)")

For more information about the ZeroMQ low level API, please consult the ZeroMQ 4.2 API.

High level API

High-level API is available once you import this module under the SwiftyZeroMQ virtual namespace (i.e. struct). The following sections describe the high-level API.

API documentation

You can also access the CocoaDocs API docs through your browser or use Xcode Quick help.

Error Handling

All the methods currently throw a ZeroMQError which implements Error and CustomStringConvertible. To handle it, please use:

do {
    let _ = try SwiftyZeroMQ.Context()
} catch {
    print("Context creation failure: \(error)")
}

Framework & Library Version

  • To get the ZeroMQ library version as a tuple, please use SwiftyZeroMQ.version:
// Library version as a tuple
let (major, minor, patch, versionString) = SwiftyZeroMQ.version
print("ZeroMQ library version is \(major).\(minor) with patch level .\(patch)")
print("ZeroMQ library version is \(versionString)")
  • To get the ZeroMQ framework version a string, please use SwiftyZeroMQ.frameworkVersion:
// Framework version as a string
print("SwiftyZeroMQ framework version is \(SwiftyZeroMQ.frameworkVersion)")

Capability Support

Use SwiftyZero.has to check whether the ZeroMQ capability is enabled or not. The list of capabilities that can be checked:

  • .ipc - the library supports the ipc:// protocol
  • .pgm - the library supports the pgm:// protocol
  • .tipc - the library supports the tipc:// protocol
  • .norm - the library supports the norm:// protocol
  • .curve - the library supports the CURVE security mechanism
  • .gssapi - the library supports the GSSAPI security mechanism

The following examples show typical usage:

if SwiftyZeroMQ.has(.ipc) {
  print("The library supports the ipc:// protocol")
}

if SwiftyZeroMQ.has(.curve) {
  print("The library supports the CURVE security mechanism")
}

Context

The class SwiftyZeroMQ.Context is a wrapper for zmq_context and predominantly handles application-level configuration and creation of SwiftyZeroMQ.Socket instances:

let context   = SwiftyZeroMQ.Context()
let requestor = context.socket(.request)
let replier   = context.socket(.reply)

The .socket method expects an argument describing the socket type required, the full list of which is given in SwiftyZeroMQ.SocketType. For full details of the available socket types see the ZMQ Documentation.

Socket

SwiftyZeroMQ.Socket is the implementation of zmq_socket and handles sending and receiving of messages through the .send and .recv methods, as well as connecting to endpoints via the .connect and .bind methods, which allows sockets to communicate with each other.

Creation of sockets is via the context, as seen in the Context section. In order to be able to communicate sockets must connect to an endpoint:

let endpoint = "tcp://127.0.0.1:5555"
requestor.bind(endpoint)
replier.connect(endpoint)

The subtleties of .bind vs. .connect are best explained by the ZMQ Documentation.

Once connected to an endpoint, it is then possible to send and receive messages:

requestor.send("Hello SwiftyZeroMQ!")
let message = replier.recv() // message reads "Hello SwiftyZeroMQ!"

The .recv method will block the thread until a response is received, and so is often used in combination with the Poller to check whether messages are available.

Poller

Using the class SwiftyZeroMQ.Poller it is possible to poll SwiftyZeroMQ.Socket instances for status changes, such as when a socket has data to be obtained by socket.recv().

To monitor a socket, sockets must first be registered:

let poller = SwiftyZeroMQ.Poller()
try poller.register(socket: requestor, flags: .pollIn)

The flags argument gives those events which are to be monitored. Multiple events can be monitored with:

try poller.register(socket: requestor, flags: [.pollIn, .pollOut])

When poller.poll() is invoked, it returns a dictionary [Socket: PollFlags] which describes which of the monitored events have occurred. Keys are the registered sockets, while values are which of the monitored events has occurred (or PollFlags.none if none of these).

A complete list of these events is given in SwiftyZeroMQ.PollFlags; these consist of:

  • PollFlags.pollIn - data can be obtained by recv.
  • PollFlags.pollOut - data can be sent using send.
  • PollFlags.pollErr - an error has occurred.
  • PollFlags.none - no events have occurred.

Note that the poller will continue to report pollIn until recv has been called to retrieve all stored messages. Likewise pollOut will always be returned until the socket is no longer able to send messages.