Class: Beachcomber::Session

Inherits:
Object
  • Object
show all
Includes:
ResponseParsing
Defined in:
lib/beachcomber/client.rb

Overview

Session holds a persistent connection to the daemon, held open by the shared library, for #get/#get_with_flags/#put/#set_context.

Obtain a Session via Client#session:

client.session do |s|
s.set_context('/repo')
r = s.get('git.branch')
end

#refresh, #status, #hello and #introspect are also available for API-compatibility with the pre-ABI client, but the C ABI provides no session-scoped equivalents for them (only get/put/set_context reuse the persistent connection — see Task 3.6 of the client-ABI plan); they route through the parent Client's connection instead, one-shot per call.

The underlying handle is guarded by the library's own mutex: a concurrent caller on the same session gets BusyError rather than blocking or interleaving requests.

Instance Method Summary collapse

Constructor Details

#initialize(handle, client_handle) ⇒ Session

Returns a new instance of Session.



119
120
121
122
123
 
# File 'lib/beachcomber/client.rb', line 119

def initialize(handle, client_handle)
  @handle = handle
  @client_handle = client_handle
  @closed = false
end

Instance Method Details

#close ⇒ Object

Closes the underlying connection. Idempotent.



203
204
205
206
207
208
 
# File 'lib/beachcomber/client.rb', line 203

def close
  return if @closed

  @closed = true
  Beachcomber::FFI.close_session(@handle)
end

#get(key, path: nil) ⇒ Result

Reads a cached value.

Parameters:

  • key (String) —

    e.g. "git.branch" or "git"

  • path (String, nil) (defaults to: nil) —

    optional working-directory override

Returns:



139
140
141
 
# File 'lib/beachcomber/client.rb', line 139

def get(key, path: nil)
  build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, 0))
end

#get_with_flags(key, path: nil, force: false, wait: false) ⇒ Result

Reads a cached value with protocol flags.

Parameters:

  • key (String)
  • path (String, nil) (defaults to: nil)
  • force (Boolean) (defaults to: false) —

    bypass cache and recompute

  • wait (Boolean) (defaults to: false) —

    block until a fresh value is available

Returns:



150
151
152
153
 
# File 'lib/beachcomber/client.rb', line 150

def get_with_flags(key, path: nil, force: false, wait: false)
  flags = (force ? Beachcomber::FFI::GET_FORCE : 0) | (wait ? Beachcomber::FFI::GET_WAIT : 0)
  build_result(Beachcomber::FFI.call!(:bc_session_get, @handle, key, path, flags))
end

#hello ⇒ HelloInfo

Sends a hello handshake and returns server info.

Returns:



174
175
176
 
# File 'lib/beachcomber/client.rb', line 174

def hello
  parse_hello(Beachcomber::FFI.call!(:bc_hello, @client_handle))
end

#introspect(subject, duration_secs: nil) ⇒ IntrospectResponse

Introspects a daemon subsystem.

Parameters:

  • subject (String) —

    one of the IntrospectSubject constants

  • duration_secs (Numeric, nil) (defaults to: nil)

Returns:



196
197
198
199
200
 
# File 'lib/beachcomber/client.rb', line 196

def introspect(subject, duration_secs: nil)
  options_json = duration_secs ? JSON.generate(duration_secs: duration_secs) : nil
  data = Beachcomber::FFI.call!(:bc_introspect, @client_handle, subject.to_s, options_json)
  parse_introspect(subject.to_s, data)
end

#put(key, data = nil, ttl: nil, path: nil) ⇒ nil

Writes a value into the daemon cache on this session's connection. data = nil clears the entry.

Parameters:

  • key (String)
  • data (Object, nil) (defaults to: nil)
  • ttl (Numeric, String, nil) (defaults to: nil) —

    time-to-live

  • path (String, nil) (defaults to: nil)

Returns:

  • (nil) 


186
187
188
189
 
# File 'lib/beachcomber/client.rb', line 186

def put(key, data = nil, ttl: nil, path: nil)
  Beachcomber::FFI.call!(:bc_session_put, @handle, key, JSON.generate(data), ttl&.to_s, path)
  nil
end

#refresh(key, path: nil) ⇒ Object

Forces the daemon to recompute a provider/key.

Parameters:

  • key (String)
  • path (String, nil) (defaults to: nil) 


159
160
161
162
 
# File 'lib/beachcomber/client.rb', line 159

def refresh(key, path: nil)
  Beachcomber::FFI.call!(:bc_refresh, @client_handle, key, path)
  nil
end

#set_context(path) ⇒ Object

Sets the default path for subsequent #get/#get_with_flags queries on this connection.

Parameters:

  • path (String) 


129
130
131
132
 
# File 'lib/beachcomber/client.rb', line 129

def set_context(path)
  Beachcomber::FFI.call!(:bc_session_set_context, @handle, path)
  nil
end

#status ⇒ Array<CacheRow>

Returns cache rows from the daemon.

Returns:



167
168
169
 
# File 'lib/beachcomber/client.rb', line 167

def status
  parse_cache_rows(Beachcomber::FFI.call!(:bc_status, @client_handle))
end