nginx.clojure.core — ibarrick/nginx-clojure 0.4.5

Core functions.

achannel clj

(achannel)

create an asynchronous socket channal.

AsynchronousChannel clj protocol

Only works on non-threadpool mode, viz. coroutine mode or default mode.

ashutdown! clj

(ashutdown! ch how)

shutdown some kind of events trigger of the socket `how can be :soft-read :soft-write :soft-both :read :write :both. If we use :soft-xxx it won't shutdown the physical socket and just turn off the events trigger for better performance. Otherwise it will shutdown the physical socket, more details can be found from http://linux.die.net/man/2/shutdown

arecv! clj

(arecv! ch buf attachment on-err on-done)

receive data from the channel. buf can be byte[] or ByteBufferon-err and on-done are functions which have the form (fn[status,attachment] when passed toon-err, status is an error code which is eof (0) or range from NginxClojureAsynSocket.NGX_HTTP_CLOJURE_SOCKET_ERR to NGX_HTTP_CLOJURE_SOCKET_ERR_OUTOFMEMORY when passed toon-done `status is always > 0 and means number of bytes received.

aset-context! clj

(aset-context! ch ctx)

asend! clj

(asend! ch data attachment on-err on-done)

send data to the channel. data can be String, byte[] or ByteBufferon-err and on-done are functions which have the form (fn[status,attachment] when passed toon-err, status is an error code which is eof (0) or range from NginxClojureAsynSocket.NGX_HTTP_CLOJURE_SOCKET_ERR to NGX_HTTP_CLOJURE_SOCKET_ERR_OUTOFMEMORY when passed toon-done `status is always > 0 and means number of bytes sent.

aclose! clj

(aclose! ch)

Close the channel

aclosed? clj

(aclosed? ch)

aget-context clj

(aget-context ch)

aconnect! clj

(aconnect! ch url attachment on-err on-done)

Connect to the remote url. url can be "192.168.2.34:80" , "www.bing.com:80", or unix domain socket "unix:/var/mytest/server.sock"on-err and on-done are functions which have the form (fn[status,attachment] when passed toon-err, status is an error code which range from NginxClojureAsynSocket.NGX_HTTP_CLOJURE_SOCKET_ERR to NGX_HTTP_CLOJURE_SOCKET_ERR_OUTOFMEMORY when passed toon-done `status is always 0.

error-str clj

(error-str ch code)

return the error string message from the error code

aset-timeout! clj

(aset-timeout! ch connect-timeout read-timeout write-timeout)

The timeout unit is millisecond. if timeout < 0 it will be ignored, if timeout = 0 it means no timeout settings

broadcast! clj

(broadcast! event)

Broadcast a event to all nginx worker processes. This function can be used to notify all subscribers in different nginx worker processes from the same nginx instance. event has the form {:data data} or {:tag tag, :data data}data can be Long, String, byte[]. If it is long integer it must be less than 0x0100000000000000L If it is string or bytes, it must be less than PIPE_BUF - 8, generally on Linux/Windows is 4088, on MacosX is 504 data will be truncated if its length exceeds this limitation. Iftag is given, data can also be long integer which means this event is very simple and only has a event id without any body or body is stored externally. The default tag value is 0x20 whenmsg is Long otherwise the default value is 0x80. Here is a list of `tag values range:

• System Event :0x00 ~ 0x1f -- Application should not use them
  • Application Event : 0x20 ~ 0xff
  • Simple Event : 0x00 ~ 0x7f, only event id (7Byte), no message body
  • Complex Event : 0x80 ~ 0xff

build-topic! clj

(build-topic! name)

co-pcalls clj

(co-pcalls & fns)

Executes the no-arg fns in parallel coroutines, returning a sequence of their values If there's no coroutine support, it will turn to use thread pool to make testing with lein-ring easy. e.g. fetch two services in parallel: (let [[r1, r2] (co-pcalls (fn[] (client/get "http://page1-url")) (fn[] (client/get "http://page2-url")))] ;println bodies of two remote responses (println (str (:body r1) "====\n" (:body r2) ))

co-pvalues clj macro

(co-pvalues & exprs)

Returns a sequence of the values of the exprs, which are evaluated in parallel coroutines. If there's no coroutine support, it will turn to use thread pool to make testing with lein-ring easy. e.g. fetch two services in parallel: (let [[r1, r2] (co-pvalues (client/get "http://page1-url") (client/get "http://page2-url"))] ;println bodies of two remote responses (println (str (:body r1) "====\n" (:body r2) ))

get-ngx-var clj

(get-ngx-var req name)

get nginx variable

hijack! clj

(hijack! req ignore-nginx-filter?)

Hijack a nginx request and return a server channel. After being hijacked, the ring handler's result will be ignored. If ignore-nginx-filter? is true all data output to channel won't be filtered by any nginx HTTP header/body filters such as gzip filter, chucked filter, etc. We can use this function to implement long polling / Server Sent Events (SSE) easily.

HttpServerChannel clj protocol

add-listener! clj

(add-listener! ch callbacks-map)

Add a channel event listener. callbacks-map is a map whose key can be either of :on-open,:on-message,:on-close,:on-error the value of :on-open is a function like (fn[ch]...) the value of :on-message is a function like (fn[ch message remaining?]...) the value of :on-close is a function like (fn[ch reason]...) the value of :on-error is a function like (fn[ch status])

close! clj

(close! ch)

Asynchronously close the channel. If there's remaining data to send it won't block current thread and will flush data on the background asynchronously and later close the channel safely

send-response! clj

(send-response! ch resp)

Asynchronously send a complete HTTP response to channel and close channel after all data are sent. resp is a ring Response Map, e.g. {:status 200, headers {"Content-Type" "text/html"}, :body "Hello, Nginx-Clojure!" } .

send! clj

(send! ch data flush? last?)

Asynchronously send data to channel without blocking current thread. data can be byte[], String, or ByteBuffer If flush? is false it will put data into buffers chain eitherwise it will write data to network. If close? is true it will close channel after all data are sent.

set-context! clj

(set-context! ch ctx)

send-header! clj

(send-header! ch status headers flush? last?)

Asynchronously send HTTP status & headers to channel. status is a integer for HTTP status code, headers is a HTTP headers map. If flush? is false it will put data into buffers chain eitherwise it will write data to network. If close? is true it will close channel after all data are sent.

on-close! clj

(on-close! ch attachment listener)

Add a close event listener. attachement is a object which will be passed to listener when close event happenslistener is a function like (fn[attachement] ... ) A close event will happen immediately when channel is closed by either of these three cases: (1) channel close function/method is invoked on this channel, e.g. (close! ch) (2) inner unrecoverable error happens with this channel, e.g. not enough memory to read/write (3) remote client connection is closed or broken.

get-context clj

(get-context ch)

websocket-upgrade! clj

(websocket-upgrade! ch send-err-for-nonwebsocekt?)

Send upgrade headers and return true if upgrade success If send-err-for-nonwebsocekt? is true it will send error response.

closed? clj

(closed? ch)

add-aggregated-listener! clj

(add-aggregated-listener! ch max-message-size callbacks-map)

Add an aggregated message listener. callbacks-map is a map whose key can be either of :on-open,:on-message,:on-close,:on-error the value of :on-open is a function like (fn[ch]...) the value of :on-message is a function like (fn[ch message]...) the value of :on-close is a function like (fn[ch reason]...) the value of :on-error is a function like (fn[ch status])

on-broadcast! clj

(on-broadcast! f)

Add a broadcasted event listener and return a removal function to delete the listener Function f is like (fn[event] ... ) and event has the form {:tag tag, :data bytes or long, :offset offset :length length } offset &length are meamingless if data is a long integer.

on-broadcast-event-decode! clj

(on-broadcast-event-decode! tester decoder)

Add a pair of tester & decoder to broadcast event decoder chain and return a removal function to delete the decoder. Decoders will be called one by one and the current decode result will be past to the next decoder. Decoders should return decoded event which has the form {:tag tag, :data any type of data, :offset offset :length length } offset & `length are meamingless if data is a long integer. Function tester is a checker and only if it return true the decoder will be invoked.

phase-done clj

phrase-done clj

process-id clj

PubSubTopic clj protocol

destory! clj

(destory! topic)

Destory the topic.

pub! clj

(pub! topic message)

Publishs a message to the topic

sub! clj

(sub! topic att callback)

Subscribes to a topic and returns an unsubscribing function. When a message comes the callback function will be invoked. e.g. (def my-topic (build-topic! "my-topic")) (sub! my-topic (atomic 0) (function [message counter] (println "received :" message ", times=" (swap counter inc)))

set-ngx-var! clj

(set-ngx-var! req name val)

set nginx variable

without-coroutine clj

(without-coroutine f)

wrap a handler f to a new handler which will keep away the coroutine context